original/man7/socket.7

   1 '\" t
   2 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   3 .\" and copyright (c) 1999 Matthew Wilcox.
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   6 .\" Permission is granted to distribute possibly modified copies
   7 .\" of this page provided the header is included verbatim,
   8 .\" and in case of nontrivial modification author and date
   9 .\" of the modification is added to the header.
  10 .\" %%%LICENSE_END
  11 .\"
  12 .\" 2002-10-30, Michael Kerrisk, <mtk.manpages@gmail.com>
  13 .\"     Added description of SO_ACCEPTCONN
  14 .\" 2004-05-20, aeb, added SO_RCVTIMEO/SO_SNDTIMEO text.
  15 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  16 .\"     Added notes on capability requirements
  17 .\"     A few small grammar fixes
  18 .\" 2010-06-13 Jan Engelhardt <jengelh@medozas.de>
  19 .\"     Documented SO_DOMAIN and SO_PROTOCOL.
  20 .\" FIXME
  21 .\" The following are not yet documented:
  22 .\"     SO_PEERNAME (2.4?)
  23 .\"             get only
  24 .\"             Seems to do something similar to getpeername(), but then
  25 .\"             why is it necessary / how does it differ?
  26 .\"     SO_TIMESTAMPNS (2.6.22)
  27 .\"             Documentation/networking/timestamping.txt
  28 .\"             commit 92f37fd2ee805aa77925c1e64fd56088b46094fc
  29 .\"             Author: Eric Dumazet <dada1@cosmosbay.com>
  30 .\"     SO_TIMESTAMPING (2.6.30)
  31 .\"             Documentation/networking/timestamping.txt
  32 .\"             commit cb9eff097831007afb30d64373f29d99825d0068
  33 .\"             Author: Patrick Ohly <patrick.ohly@intel.com>
  34 .\"     SO_WIFI_STATUS (3.3)
  35 .\"             commit 6e3e939f3b1bf8534b32ad09ff199d88800835a0
  36 .\"             Author: Johannes Berg <johannes.berg@intel.com>
  37 .\"             Also: SCM_WIFI_STATUS
  38 .\"     SO_NOFCS (3.4)
  39 .\"             commit 3bdc0eba0b8b47797f4a76e377dd8360f317450f
  40 .\"             Author: Ben Greear <greearb@candelatech.com>
  41 .\"     SO_GET_FILTER (3.8)
  42 .\"             commit a8fc92778080c845eaadc369a0ecf5699a03bef0
  43 .\"             Author: Pavel Emelyanov <xemul@parallels.com>
  44 .\"     SO_REUSEPORT (3.9)
  45 .\"             commit c617f398edd4db2b8567a28e899a88f8f574798d
  46 .\"             https://lwn.net/Articles/542629/
  47 .\"     SO_LOCK_FILTER (3.9)
  48 .\"             commit d59577b6ffd313d0ab3be39cb1ab47e29bdc9182
  49 .\"             Author: Vincent Bernat <bernat@luffy.cx>
  50 .\"     SO_SELECT_ERR_QUEUE (3.10)
  51 .\"             commit 7d4c04fc170087119727119074e72445f2bb192b
  52 .\"             Author: Keller, Jacob E <jacob.e.keller@intel.com>
  53 .\"     SO_MAX_PACING_RATE (3.13)
  54 .\"             commit 62748f32d501f5d3712a7c372bbb92abc7c62bc7
  55 .\"     SO_BPF_EXTENSIONS (3.14)
  56 .\"             commit ea02f9411d9faa3553ed09ce0ec9f00ceae9885e
  57 .\"
  58 .TH SOCKET 7 2014-07-08 Linux "Linux Programmer's Manual"
  59 .SH NAME
  60 socket \- Linux socket interface
  61 .SH SYNOPSIS
  62 .B #include <sys/socket.h>
  63 .sp
  64 .IB sockfd " = socket(int " socket_family ", int " socket_type ", int " protocol );
  65 .SH DESCRIPTION
  66 This manual page describes the Linux networking socket layer user
  67 interface.
  68 The BSD compatible sockets
  69 are the uniform interface
  70 between the user process and the network protocol stacks in the kernel.
  71 The protocol modules are grouped into
  72 .I protocol families
  73 such as
  74 .BR AF_INET ", " AF_IPX ", and " AF_PACKET ,
  75 and
  76 .I socket types
  77 such as
  78 .B SOCK_STREAM
  79 or
  80 .BR SOCK_DGRAM .
  81 See
  82 .BR socket (2)
  83 for more information on families and types.
  84 .SS Socket-layer functions
  85 These functions are used by the user process to send or receive packets
  86 and to do other socket operations.
  87 For more information see their respective manual pages.
  88
  89 .BR socket (2)
  90 creates a socket,
  91 .BR connect (2)
  92 connects a socket to a remote socket address,
  93 the
  94 .BR bind (2)
  95 function binds a socket to a local socket address,
  96 .BR listen (2)
  97 tells the socket that new connections shall be accepted, and
  98 .BR accept (2)
  99 is used to get a new socket with a new incoming connection.
 100 .BR socketpair (2)
 101 returns two connected anonymous sockets (implemented only for a few
 102 local families like
 103 .BR AF_UNIX )
 104 .PP
 105 .BR send (2),
 106 .BR sendto (2),
 107 and
 108 .BR sendmsg (2)
 109 send data over a socket, and
 110 .BR recv (2),
 111 .BR recvfrom (2),
 112 .BR recvmsg (2)
 113 receive data from a socket.
 114 .BR poll (2)
 115 and
 116 .BR select (2)
 117 wait for arriving data or a readiness to send data.
 118 In addition, the standard I/O operations like
 119 .BR write (2),
 120 .BR writev (2),
 121 .BR sendfile (2),
 122 .BR read (2),
 123 and
 124 .BR readv (2)
 125 can be used to read and write data.
 126 .PP
 127 .BR getsockname (2)
 128 returns the local socket address and
 129 .BR getpeername (2)
 130 returns the remote socket address.
 131 .BR getsockopt (2)
 132 and
 133 .BR setsockopt (2)
 134 are used to set or get socket layer or protocol options.
 135 .BR ioctl (2)
 136 can be used to set or read some other options.
 137 .PP
 138 .BR close (2)
 139 is used to close a socket.
 140 .BR shutdown (2)
 141 closes parts of a full-duplex socket connection.
 142 .PP
 143 Seeking, or calling
 144 .BR pread (2)
 145 or
 146 .BR pwrite (2)
 147 with a nonzero position is not supported on sockets.
 148 .PP
 149 It is possible to do nonblocking I/O on sockets by setting the
 150 .B O_NONBLOCK
 151 flag on a socket file descriptor using
 152 .BR fcntl (2).
 153 Then all operations that would block will (usually)
 154 return with
 155 .B EAGAIN
 156 (operation should be retried later);
 157 .BR connect (2)
 158 will return
 159 .B EINPROGRESS
 160 error.
 161 The user can then wait for various events via
 162 .BR poll (2)
 163 or
 164 .BR select (2).
 165 .TS
 166 tab(:) allbox;
 167 c s s
 168 l l l.
 169 I/O events
 170 Event:Poll flag:Occurrence
 171 Read:POLLIN:T{
 172 New data arrived.
 173 T}
 174 Read:POLLIN:T{
 175 A connection setup has been completed
 176 (for connection-oriented sockets)
 177 T}
 178 Read:POLLHUP:T{
 179 A disconnection request has been initiated by the other end.
 180 T}
 181 Read:POLLHUP:T{
 182 A connection is broken (only for connection-oriented protocols).
 183 When the socket is written
 184 .B SIGPIPE
 185 is also sent.
 186 T}
 187 Write:POLLOUT:T{
 188 Socket has enough send buffer space for writing new data.
 189 T}
 190 Read/Write:T{
 191 POLLIN|
 192 .br
 193 POLLOUT
 194 T}:T{
 195 An outgoing
 196 .BR connect (2)
 197 finished.
 198 T}
 199 Read/Write:POLLERR:An asynchronous error occurred.
 200 Read/Write:POLLHUP:The other end has shut down one direction.
 201 Exception:POLLPRI:T{
 202 Urgent data arrived.
 203 .B SIGURG
 204 is sent then.
 205 T}
 206 .\" FIXME . The following is not true currently:
 207 .\" It is no I/O event when the connection
 208 .\" is broken from the local end using
 209 .\" .BR shutdown (2)
 210 .\" or
 211 .\" .BR close (2).
 212 .TE
 213 .PP
 214 An alternative to
 215 .BR poll (2)
 216 and
 217 .BR select (2)
 218 is to let the kernel inform the application about events
 219 via a
 220 .B SIGIO
 221 signal.
 222 For that the
 223 .B O_ASYNC
 224 flag must be set on a socket file descriptor via
 225 .BR fcntl (2)
 226 and a valid signal handler for
 227 .B SIGIO
 228 must be installed via
 229 .BR sigaction (2).
 230 See the
 231 .I Signals
 232 discussion below.
 233 .SS Socket address structures
 234 Each socket domain has its own format for socket addresses,
 235 with a domain-specific address structure.
 236 Each of these structures begins with an
 237 integer "family" field (typed as
 238 .IR sa_family_t )
 239 that indicates the type of the address structure.
 240 This allows
 241 the various system calls (e.g.,
 242 .BR connect (2),
 243 .BR bind (2),
 244 .BR accept (2),
 245 .BR getsockname (2),
 246 .BR getpeername (2)),
 247 which are generic to all socket domains,
 248 to determine the domain of a particular socket address.
 249
 250 To allow any type of socket address to be passed to
 251 interfaces in the sockets API,
 252 the type
 253 .IR "struct sockaddr"
 254 is defined.
 255 The purpose of this type is purely to allow casting of
 256 domain-specific socket address types to a "generic" type,
 257 so as to avoid compiler warnings about type mismatches in
 258 calls to the sockets API.
 259
 260 In addition, the sockets API provides the data type
 261 .IR "struct sockaddr_storage".
 262 This type
 263 is suitable to accommodate all supported domain-specific socket
 264 address structures; it is large enough and is aligned properly.
 265 (In particular, it is large enough to hold
 266 IPv6 socket addresses.)
 267 The structure includes the following field, which can be used to identify
 268 the type of socket address actually stored in the structure:
 269
 270 .in +4n
 271 .nf
 272     sa_family_t ss_family;
 273 .fi
 274 .in
 275
 276 The
 277 .I sockaddr_storage
 278 structure is useful in programs that must handle socket addresses
 279 in a generic way
 280 (e.g., programs that must deal with both IPv4 and IPv6 socket addresses).
 281 .SS Socket options
 282 The socket options listed below can be set by using
 283 .BR setsockopt (2)
 284 and read with
 285 .BR getsockopt (2)
 286 with the socket level set to
 287 .B SOL_SOCKET
 288 for all sockets.
 289 Unless otherwise noted,
 290 .I optval
 291 is a pointer to an
 292 .IR int .
 293 .\" FIXME .
 294 .\" In the list below, the text used to describe argument types
 295 .\" for each socket option should be more consistent
 296 .\"
 297 .\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in
 298 .\" W R Stevens, UNPv1
 299 .TP
 300 .B SO_ACCEPTCONN
 301 Returns a value indicating whether or not this socket has been marked
 302 to accept connections with
 303 .BR listen (2).
 304 The value 0 indicates that this is not a listening socket,
 305 the value 1 indicates that this is a listening socket.
 306 This socket option is read-only.
 307 .TP
 308 .B SO_BINDTODEVICE
 309 Bind this socket to a particular device like \(lqeth0\(rq,
 310 as specified in the passed interface name.
 311 If the
 312 name is an empty string or the option length is zero, the socket device
 313 binding is removed.
 314 The passed option is a variable-length null-terminated
 315 interface name string with the maximum size of
 316 .BR IFNAMSIZ .
 317 If a socket is bound to an interface,
 318 only packets received from that particular interface are processed by the
 319 socket.
 320 Note that this works only for some socket types, particularly
 321 .B AF_INET
 322 sockets.
 323 It is not supported for packet sockets (use normal
 324 .BR bind (2)
 325 there).
 326
 327 Before Linux 3.8,
 328 this socket option could be set, but could not retrieved with
 329 .BR getsockopt (2).
 330 Since Linux 3.8, it is readable.
 331 The
 332 .I optlen
 333 argument should contain the buffer size available
 334 to receive the device name and is recommended to be
 335 .BR IFNAMSZ
 336 bytes.
 337 The real device name length is reported back in the
 338 .I optlen
 339 argument.
 340 .TP
 341 .B SO_BROADCAST
 342 Set or get the broadcast flag.
 343 When enabled, datagram sockets are allowed to send
 344 packets to a broadcast address.
 345 This option has no effect on stream-oriented sockets.
 346 .TP
 347 .B SO_BSDCOMPAT
 348 Enable BSD bug-to-bug compatibility.
 349 This is used by the UDP protocol module in Linux 2.0 and 2.2.
 350 If enabled, ICMP errors received for a UDP socket will not be passed
 351 to the user program.
 352 In later kernel versions, support for this option has been phased out:
 353 Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning
 354 (printk()) if a program uses this option.
 355 Linux 2.0 also enabled BSD bug-to-bug compatibility
 356 options (random header changing, skipping of the broadcast flag) for raw
 357 sockets with this option, but that was removed in Linux 2.2.
 358 .TP
 359 .B SO_DEBUG
 360 Enable socket debugging.
 361 Only allowed for processes with the
 362 .B CAP_NET_ADMIN
 363 capability or an effective user ID of 0.
 364 .TP
 365 .BR SO_DOMAIN " (since Linux 2.6.32)"
 366 Retrieves the socket domain as an integer, returning a value such as
 367 .BR AF_INET6 .
 368 See
 369 .BR socket (2)
 370 for details.
 371 This socket option is read-only.
 372 .TP
 373 .B SO_ERROR
 374 Get and clear the pending socket error.
 375 This socket option is read-only.
 376 Expects an integer.
 377 .TP
 378 .B SO_DONTROUTE
 379 Don't send via a gateway, send only to directly connected hosts.
 380 The same effect can be achieved by setting the
 381 .B MSG_DONTROUTE
 382 flag on a socket
 383 .BR send (2)
 384 operation.
 385 Expects an integer boolean flag.
 386 .TP
 387 .B SO_KEEPALIVE
 388 Enable sending of keep-alive messages on connection-oriented sockets.
 389 Expects an integer boolean flag.
 390 .TP
 391 .B SO_LINGER
 392 Sets or gets the
 393 .B SO_LINGER
 394 option.
 395 The argument is a
 396 .I linger
 397 structure.
 398 .sp
 399 .in +4n
 400 .nf
 401 struct linger {
 402     int l_onoff;    /* linger active */
 403     int l_linger;   /* how many seconds to linger for */
 404 };
 405 .fi
 406 .in
 407 .IP
 408 When enabled, a
 409 .BR close (2)
 410 or
 411 .BR shutdown (2)
 412 will not return until all queued messages for the socket have been
 413 successfully sent or the linger timeout has been reached.
 414 Otherwise,
 415 the call returns immediately and the closing is done in the background.
 416 When the socket is closed as part of
 417 .BR exit (2),
 418 it always lingers in the background.
 419 .TP
 420 .BR SO_MARK " (since Linux 2.6.25)"
 421 .\" commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0
 422 .\" and    914a9ab386a288d0f22252fc268ecbc048cdcbd5
 423 Set the mark for each packet sent through this socket
 424 (similar to the netfilter MARK target but socket-based).
 425 Changing the mark can be used for mark-based
 426 routing without netfilter or for packet filtering.
 427 Setting this option requires the
 428 .B CAP_NET_ADMIN
 429 capability.
 430 .TP
 431 .B SO_OOBINLINE
 432 If this option is enabled,
 433 out-of-band data is directly placed into the receive data stream.
 434 Otherwise, out-of-band data is passed only when the
 435 .B MSG_OOB
 436 flag is set during receiving.
 437 .\" don't document it because it can do too much harm.
 438 .\".B SO_NO_CHECK
 439 .TP
 440 .B SO_PASSCRED
 441 Enable or disable the receiving of the
 442 .B SCM_CREDENTIALS
 443 control message.
 444 For more information see
 445 .BR unix (7).
 446 .\" FIXME Document SO_PASSSEC, added in 2.6.18; there is some info
 447 .\" in the 2.6.18 ChangeLog
 448 .TP
 449 .BR SO_PEEK_OFF " (since Linux 3.4)"
 450 .\" commit ef64a54f6e558155b4f149bb10666b9e914b6c54
 451 This option, which is currently supported only for
 452 .BR unix (7)
 453 sockets, sets the value of the "peek offset" for the
 454 .BR recv (2)
 455 system call when used with
 456 .BR MSG_PEEK
 457 flag.
 458
 459 When this option is set to a negative value
 460 (it is set to \-1 for all new sockets),
 461 traditional behavior is provided:
 462 .BR recv (2)
 463 with the
 464 .BR MSG_PEEK
 465 flag will peek data from the front of the queue.
 466
 467 When the option is set to a value greater than or equal to zero,
 468 then the next peek at data queued in the socket will occur at
 469 the byte offset specified by the option value.
 470 At the same time, the "peek offset" will be
 471 incremented by the number of bytes that were peeked from the queue,
 472 so that a subsequent peek will return the next data in the queue.
 473
 474 If data is removed from the front of the queue via a call to
 475 .BR recv (2)
 476 (or similar) without the
 477 .BR MSG_PEEK
 478 flag, the "peek offset" will be decreased by the number of bytes removed.
 479 In other words, receiving data without the
 480 .B MSG_PEEK
 481 flag will cause the "peek offset" to be adjusted to maintain
 482 the correct relative position in the queued data,
 483 so that a subsequent peek will retrieve the data that would have been
 484 retrieved had the data not been removed.
 485
 486 For datagram sockets, if the "peek offset" points to the middle of a packet,
 487 the data returned will be marked with the
 488 .BR MSG_TRUNC
 489 flag.
 490
 491 The following example serves to illustrate the use of
 492 .BR SO_PEEK_OFF .
 493 Suppose a stream socket has the following queued input data:
 494
 495     aabbccddeeff
 496
 497 .IP
 498 The following sequence of
 499 .BR recv (2)
 500 calls would have the effect noted in the comments:
 501
 502 .in +4n
 503 .nf
 504 int ov = 4;                  // Set peek offset to 4
 505 setsockopt(fd, SOL_SOCKET, SO_PEEK_OFF, &ov, sizeof(ov));
 506
 507 recv(fd, buf, 2, MSG_PEEK);  // Peeks "cc"; offset set to 6
 508 recv(fd, buf, 2, MSG_PEEK);  // Peeks "dd"; offset set to 8
 509 recv(fd, buf, 2, 0);         // Reads "aa"; offset set to 6
 510 recv(fd, buf, 2, MSG_PEEK);  // Peeks "ee"; offset set to 8
 511 .fi
 512 .in
 513 .TP
 514 .B SO_PEERCRED
 515 Return the credentials of the foreign process connected to this socket.
 516 This is possible only for connected
 517 .B AF_UNIX
 518 stream sockets and
 519 .B AF_UNIX
 520 stream and datagram socket pairs created using
 521 .BR socketpair (2);
 522 see
 523 .BR unix (7).
 524 The returned credentials are those that were in effect at the time
 525 of the call to
 526 .BR connect (2)
 527 or
 528 .BR socketpair (2).
 529 The argument is a
 530 .I ucred
 531 structure; define the
 532 .B _GNU_SOURCE
 533 feature test macro to obtain the definition of that structure from
 534 .IR <sys/socket.h> .
 535 This socket option is read-only.
 536 .TP
 537 .B SO_PRIORITY
 538 Set the protocol-defined priority for all packets to be sent on
 539 this socket.
 540 Linux uses this value to order the networking queues:
 541 packets with a higher priority may be processed first depending
 542 on the selected device queueing discipline.
 543 For
 544 .BR ip (7),
 545 this also sets the IP type-of-service (TOS) field for outgoing packets.
 546 Setting a priority outside the range 0 to 6 requires the
 547 .B CAP_NET_ADMIN
 548 capability.
 549 .TP
 550 .BR SO_PROTOCOL " (since Linux 2.6.32)"
 551 Retrieves the socket protocol as an integer, returning a value such as
 552 .BR IPPROTO_SCTP .
 553 See
 554 .BR socket (2)
 555 for details.
 556 This socket option is read-only.
 557 .TP
 558 .B SO_RCVBUF
 559 Sets or gets the maximum socket receive buffer in bytes.
 560 The kernel doubles this value (to allow space for bookkeeping overhead)
 561 when it is set using
 562 .\" Most (all?) other implementations do not do this -- MTK, Dec 05
 563 .BR setsockopt (2),
 564 and this doubled value is returned by
 565 .BR getsockopt (2).
 566 .\" The following thread on LMKL is quite informative:
 567 .\" getsockopt/setsockopt with SO_RCVBUF and SO_SNDBUF "non-standard" behavior
 568 .\" 17 July 2012
 569 .\" http://thread.gmane.org/gmane.linux.kernel/1328935
 570 The default value is set by the
 571 .I /proc/sys/net/core/rmem_default
 572 file, and the maximum allowed value is set by the
 573 .I /proc/sys/net/core/rmem_max
 574 file.
 575 The minimum (doubled) value for this option is 256.
 576 .TP
 577 .BR SO_RCVBUFFORCE " (since Linux 2.6.14)"
 578 Using this socket option, a privileged
 579 .RB ( CAP_NET_ADMIN )
 580 process can perform the same task as
 581 .BR SO_RCVBUF ,
 582 but the
 583 .I rmem_max
 584 limit can be overridden.
 585 .TP
 586 .BR SO_RCVLOWAT " and " SO_SNDLOWAT
 587 Specify the minimum number of bytes in the buffer until the socket layer
 588 will pass the data to the protocol
 589 .RB ( SO_SNDLOWAT )
 590 or the user on receiving
 591 .RB ( SO_RCVLOWAT ).
 592 These two values are initialized to 1.
 593 .B SO_SNDLOWAT
 594 is not changeable on Linux
 595 .RB ( setsockopt (2)
 596 fails with the error
 597 .BR ENOPROTOOPT ).
 598 .B SO_RCVLOWAT
 599 is changeable
 600 only since Linux 2.4.
 601 The
 602 .BR select (2)
 603 and
 604 .BR poll (2)
 605 system calls currently do not respect the
 606 .B SO_RCVLOWAT
 607 setting on Linux,
 608 and mark a socket readable when even a single byte of data is available.
 609 A subsequent read from the socket will block until
 610 .B SO_RCVLOWAT
 611 bytes are available.
 612 .\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2
 613 .\" Tested on kernel 2.6.14 -- mtk, 30 Nov 05
 614 .TP
 615 .BR SO_RCVTIMEO " and " SO_SNDTIMEO
 616 .\" Not implemented in 2.0.
 617 .\" Implemented in 2.1.11 for getsockopt: always return a zero struct.
 618 .\" Implemented in 2.3.41 for setsockopt, and actually used.
 619 Specify the receiving or sending timeouts until reporting an error.
 620 The argument is a
 621 .IR "struct timeval" .
 622 If an input or output function blocks for this period of time, and
 623 data has been sent or received, the return value of that function
 624 will be the amount of data transferred; if no data has been transferred
 625 and the timeout has been reached, then \-1 is returned with
 626 .I errno
 627 set to
 628 .BR EAGAIN
 629 or
 630 .BR EWOULDBLOCK ,
 631 .\" in fact to EAGAIN
 632 or
 633 .B EINPROGRESS
 634 (for
 635 .BR connect (2))
 636 just as if the socket was specified to be nonblocking.
 637 If the timeout is set to zero (the default),
 638 then the operation will never timeout.
 639 Timeouts only have effect for system calls that perform socket I/O (e.g.,
 640 .BR read (2),
 641 .BR recvmsg (2),
 642 .BR send (2),
 643 .BR sendmsg (2));
 644 timeouts have no effect for
 645 .BR select (2),
 646 .BR poll (2),
 647 .BR epoll_wait (2),
 648 and so on.
 649 .TP
 650 .B SO_REUSEADDR
 651 Indicates that the rules used in validating addresses supplied in a
 652 .BR bind (2)
 653 call should allow reuse of local addresses.
 654 For
 655 .B AF_INET
 656 sockets this
 657 means that a socket may bind, except when there
 658 is an active listening socket bound to the address.
 659 When the listening socket is bound to
 660 .B INADDR_ANY
 661 with a specific port then it is not possible
 662 to bind to this port for any local address.
 663 Argument is an integer boolean flag.
 664 .TP
 665 .BR SO_RXQ_OVFL " (since Linux 2.6.33)"
 666 .\" commit 3b885787ea4112eaa80945999ea0901bf742707f
 667 Indicates that an unsigned 32-bit value ancillary message (cmsg)
 668 should be attached to received skbs indicating
 669 the number of packets dropped by the socket between
 670 the last received packet and this received packet.
 671 .TP
 672 .B SO_SNDBUF
 673 Sets or gets the maximum socket send buffer in bytes.
 674 The kernel doubles this value (to allow space for bookkeeping overhead)
 675 when it is set using
 676 .\" Most (all?) other implementations do not do this -- MTK, Dec 05
 677 .\" See also the comment to SO_RCVBUF (17 Jul 2012 LKML mail)
 678 .BR setsockopt (2),
 679 and this doubled value is returned by
 680 .BR getsockopt (2).
 681 The default value is set by the
 682 .I /proc/sys/net/core/wmem_default
 683 file and the maximum allowed value is set by the
 684 .I /proc/sys/net/core/wmem_max
 685 file.
 686 The minimum (doubled) value for this option is 2048.
 687 .TP
 688 .BR SO_SNDBUFFORCE " (since Linux 2.6.14)"
 689 Using this socket option, a privileged
 690 .RB ( CAP_NET_ADMIN )
 691 process can perform the same task as
 692 .BR SO_SNDBUF ,
 693 but the
 694 .I wmem_max
 695 limit can be overridden.
 696 .TP
 697 .B SO_TIMESTAMP
 698 Enable or disable the receiving of the
 699 .B SO_TIMESTAMP
 700 control message.
 701 The timestamp control message is sent with level
 702 .B SOL_SOCKET
 703 and the
 704 .I cmsg_data
 705 field is a
 706 .I "struct timeval"
 707 indicating the
 708 reception time of the last packet passed to the user in this call.
 709 See
 710 .BR cmsg (3)
 711 for details on control messages.
 712 .TP
 713 .B SO_TYPE
 714 Gets the socket type as an integer (e.g.,
 715 .BR SOCK_STREAM ).
 716 This socket option is read-only.
 717 .TP
 718 .BR SO_BUSY_POLL " (since Linux 3.11)"
 719 Sets the approximate time in microseconds to busy poll on a blocking receive
 720 when there is no data.
 721 Increasing this value requires
 722 .BR CAP_NET_ADMIN .
 723 The default for this option is controlled by the
 724 .I /proc/sys/net/core/busy_read
 725 file.
 726
 727 The value in the
 728 .I /proc/sys/net/core/busy_poll
 729 file determines how long
 730 .BR select (2)
 731 and
 732 .BR poll (2)
 733 will busy poll when they operate on sockets with
 734 .BR SO_BUSY_POLL
 735 set and no events to report are found.
 736
 737 In both cases,
 738 busy polling will only be done when the socket last received data
 739 from a network device that supports this option.
 740
 741 While busy polling may improve latency of some applications,
 742 care must be taken when using it since this will increase
 743 both CPU utilization and power usage.
 744 .SS Signals
 745 When writing onto a connection-oriented socket that has been shut down
 746 (by the local or the remote end)
 747 .B SIGPIPE
 748 is sent to the writing process and
 749 .B EPIPE
 750 is returned.
 751 The signal is not sent when the write call
 752 specified the
 753 .B MSG_NOSIGNAL
 754 flag.
 755 .PP
 756 When requested with the
 757 .B FIOSETOWN
 758 .BR fcntl (2)
 759 or
 760 .B SIOCSPGRP
 761 .BR ioctl (2),
 762 .B SIGIO
 763 is sent when an I/O event occurs.
 764 It is possible to use
 765 .BR poll (2)
 766 or
 767 .BR select (2)
 768 in the signal handler to find out which socket the event occurred on.
 769 An alternative (in Linux 2.2) is to set a real-time signal using the
 770 .B F_SETSIG
 771 .BR fcntl (2);
 772 the handler of the real time signal will be called with
 773 the file descriptor in the
 774 .I si_fd
 775 field of its
 776 .IR siginfo_t .
 777 See
 778 .BR fcntl (2)
 779 for more information.
 780 .PP
 781 Under some circumstances (e.g., multiple processes accessing a
 782 single socket), the condition that caused the
 783 .B SIGIO
 784 may have already disappeared when the process reacts to the signal.
 785 If this happens, the process should wait again because Linux
 786 will resend the signal later.
 787 .\" .SS Ancillary messages
 788 .SS /proc interfaces
 789 The core socket networking parameters can be accessed
 790 via files in the directory
 791 .IR /proc/sys/net/core/ .
 792 .TP
 793 .I rmem_default
 794 contains the default setting in bytes of the socket receive buffer.
 795 .TP
 796 .I rmem_max
 797 contains the maximum socket receive buffer size in bytes which a user may
 798 set by using the
 799 .B SO_RCVBUF
 800 socket option.
 801 .TP
 802 .I wmem_default
 803 contains the default setting in bytes of the socket send buffer.
 804 .TP
 805 .I wmem_max
 806 contains the maximum socket send buffer size in bytes which a user may
 807 set by using the
 808 .B SO_SNDBUF
 809 socket option.
 810 .TP
 811 .IR message_cost " and " message_burst
 812 configure the token bucket filter used to load limit warning messages
 813 caused by external network events.
 814 .TP
 815 .I netdev_max_backlog
 816 Maximum number of packets in the global input queue.
 817 .TP
 818 .I optmem_max
 819 Maximum length of ancillary data and user control data like the iovecs
 820 per socket.
 821 .\" netdev_fastroute is not documented because it is experimental
 822 .SS Ioctls
 823 These operations can be accessed using
 824 .BR ioctl (2):
 825
 826 .in +4n
 827 .nf
 828 .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");"
 829 .fi
 830 .in
 831 .TP
 832 .B SIOCGSTAMP
 833 Return a
 834 .I struct timeval
 835 with the receive timestamp of the last packet passed to the user.
 836 This is useful for accurate round trip time measurements.
 837 See
 838 .BR setitimer (2)
 839 for a description of
 840 .IR "struct timeval" .
 841 .\"
 842 This ioctl should be used only if the socket option
 843 .B SO_TIMESTAMP
 844 is not set on the socket.
 845 Otherwise, it returns the timestamp of the
 846 last packet that was received while
 847 .B SO_TIMESTAMP
 848 was not set, or it fails if no such packet has been received,
 849 (i.e.,
 850 .BR ioctl (2)
 851 returns \-1 with
 852 .I errno
 853 set to
 854 .BR ENOENT ).
 855 .TP
 856 .B SIOCSPGRP
 857 Set the process or process group to send
 858 .B SIGIO
 859 or
 860 .B SIGURG
 861 signals
 862 to when an
 863 asynchronous I/O operation has finished or urgent data is available.
 864 The argument is a pointer to a
 865 .IR pid_t .
 866 If the argument is positive, send the signals to that process.
 867 If the
 868 argument is negative, send the signals to the process group with the ID
 869 of the absolute value of the argument.
 870 The process may only choose itself or its own process group to receive
 871 signals unless it has the
 872 .B CAP_KILL
 873 capability or an effective UID of 0.
 874 .TP
 875 .B FIOASYNC
 876 Change the
 877 .B O_ASYNC
 878 flag to enable or disable asynchronous I/O mode of the socket.
 879 Asynchronous I/O mode means that the
 880 .B SIGIO
 881 signal or the signal set with
 882 .B F_SETSIG
 883 is raised when a new I/O event occurs.
 884 .IP
 885 Argument is an integer boolean flag.
 886 (This operation is synonymous with the use of
 887 .BR fcntl (2)
 888 to set the
 889 .B O_ASYNC
 890 flag.)
 891 .\"
 892 .TP
 893 .B SIOCGPGRP
 894 Get the current process or process group that receives
 895 .B SIGIO
 896 or
 897 .B SIGURG
 898 signals,
 899 or 0
 900 when none is set.
 901 .PP
 902 Valid
 903 .BR fcntl (2)
 904 operations:
 905 .TP
 906 .B FIOGETOWN
 907 The same as the
 908 .B SIOCGPGRP
 909 .BR ioctl (2).
 910 .TP
 911 .B FIOSETOWN
 912 The same as the
 913 .B SIOCSPGRP
 914 .BR ioctl (2).
 915 .SH VERSIONS
 916 .B SO_BINDTODEVICE
 917 was introduced in Linux 2.0.30.
 918 .B SO_PASSCRED
 919 is new in Linux 2.2.
 920 The
 921 .I /proc
 922 interfaces was introduced in Linux 2.2.
 923 .B SO_RCVTIMEO
 924 and
 925 .B SO_SNDTIMEO
 926 are supported since Linux 2.3.41.
 927 Earlier, timeouts were fixed to
 928 a protocol-specific setting, and could not be read or written.
 929 .SH NOTES
 930 Linux assumes that half of the send/receive buffer is used for internal
 931 kernel structures; thus the values in the corresponding
 932 .I /proc
 933 files are twice what can be observed on the wire.
 934
 935 Linux will only allow port reuse with the
 936 .B SO_REUSEADDR
 937 option
 938 when this option was set both in the previous program that performed a
 939 .BR bind (2)
 940 to the port and in the program that wants to reuse the port.
 941 This differs from some implementations (e.g., FreeBSD)
 942 where only the later program needs to set the
 943 .B SO_REUSEADDR
 944 option.
 945 Typically this difference is invisible, since, for example, a server
 946 program is designed to always set this option.
 947 .SH BUGS
 948 The
 949 .B CONFIG_FILTER
 950 socket options
 951 .B SO_ATTACH_FILTER
 952 and
 953 .B SO_DETACH_FILTER
 954 .\" FIXME Document SO_ATTACH_FILTER and SO_DETACH_FILTER
 955 are not documented.
 956 The suggested interface to use them is via the libpcap
 957 library.
 958 .\" .SH AUTHORS
 959 .\" This man page was written by Andi Kleen.
 960 .SH SEE ALSO
 961 .BR connect (2),
 962 .BR getsockopt (2),
 963 .BR setsockopt (2),
 964 .BR socket (2),
 965 .BR capabilities (7),
 966 .BR ddp (7),
 967 .BR ip (7),
 968 .BR packet (7),
 969 .BR tcp (7),
 970 .BR udp (7),
 971 .BR unix (7)
 972 .SH COLOPHON
 973 This page is part of release 3.77 of the Linux
 974 .I man-pages
 975 project.
 976 A description of the project,
 977 information about reporting bugs,
 978 and the latest version of this page,
 979 can be found at
 980 \%http://www.kernel.org/doc/man\-pages/.