man7/socket.7

   1 '\" t
   2 .\" Don't change the first line, it tells man that we need tbl.
   3 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   4 .\" and copyright (c) 1999 Matthew Wilcox.
   5 .\" Permission is granted to distribute possibly modified copies
   6 .\" of this page provided the header is included verbatim,
   7 .\" and in case of nontrivial modification author and date
   8 .\" of the modification is added to the header.
   9 .\"
  10 .\" 2002-10-30, Michael Kerrisk, <mtk.manpages@gmail.com>
  11 .\"     Added description of SO_ACCEPTCONN
  12 .\" 2004-05-20, aeb, added SO_RCVTIMEO/SO_SNDTIMEO text.
  13 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  14 .\"     Added notes on capability requirements
  15 .\"     A few small grammar fixes
  16 .\"
  17 .\" FIXME probably all PF_* should be AF_* in this page, since
  18 .\"        POSIX only specifies the latter values.
  19 .\"
  20 .TH SOCKET 7 2007-08-28 Linux "Linux Programmer's Manual"
  21 .SH NAME
  22 socket \- Linux socket interface
  23 .SH SYNOPSIS
  24 .B #include <sys/socket.h>
  25 .br
  26 .IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol );
  27 .SH DESCRIPTION
  28 This manual page describes the Linux networking socket layer user
  29 interface.
  30 The BSD compatible sockets
  31 are the uniform interface
  32 between the user process and the network protocol stacks in the kernel.
  33 The protocol modules are grouped into
  34 .I protocol families
  35 like
  36 .BR PF_INET ", " PF_IPX ", " PF_PACKET
  37 and
  38 .I socket types
  39 like
  40 .B SOCK_STREAM
  41 or
  42 .BR SOCK_DGRAM .
  43 See
  44 .BR socket (2)
  45 for more information on families and types.
  46 .SS Socket Layer Functions
  47 These functions are used by the user process to send or receive packets
  48 and to do other socket operations.
  49 For more information see their respective manual pages.
  50
  51 .BR socket (2)
  52 creates a socket,
  53 .BR connect (2)
  54 connects a socket to a remote socket address,
  55 the
  56 .BR bind (2)
  57 function binds a socket to a local socket address,
  58 .BR listen (2)
  59 tells the socket that new connections shall be accepted, and
  60 .BR accept (2)
  61 is used to get a new socket with a new incoming connection.
  62 .BR socketpair (2)
  63 returns two connected anonymous sockets (only implemented for a few
  64 local families like
  65 .BR PF_UNIX )
  66 .PP
  67 .BR send (2),
  68 .BR sendto (2),
  69 and
  70 .BR sendmsg (2)
  71 send data over a socket, and
  72 .BR recv (2),
  73 .BR recvfrom (2),
  74 .BR recvmsg (2)
  75 receive data from a socket.
  76 .BR poll (2)
  77 and
  78 .BR select (2)
  79 wait for arriving data or a readiness to send data.
  80 In addition, the standard I/O operations like
  81 .BR write (2),
  82 .BR writev (2),
  83 .BR sendfile (2),
  84 .BR read (2),
  85 and
  86 .BR readv (2)
  87 can be used to read and write data.
  88 .PP
  89 .BR getsockname (2)
  90 returns the local socket address and
  91 .BR getpeername (2)
  92 returns the remote socket address.
  93 .BR getsockopt (2)
  94 and
  95 .BR setsockopt (2)
  96 are used to set or get socket layer or protocol options.
  97 .BR ioctl (2)
  98 can be used to set or read some other options.
  99 .PP
 100 .BR close (2)
 101 is used to close a socket.
 102 .BR shutdown (2)
 103 closes parts of a full duplex socket connection.
 104 .PP
 105 Seeking, or calling
 106 .BR pread (2)
 107 or
 108 .BR pwrite (2)
 109 with a non-zero position is not supported on sockets.
 110 .PP
 111 It is possible to do non-blocking I/O on sockets by setting the
 112 .B O_NONBLOCK
 113 flag on a socket file descriptor using
 114 .BR fcntl (2).
 115 Then all operations that would block will (usually)
 116 return with
 117 .B EAGAIN
 118 (operation should be retried later);
 119 .BR connect (2)
 120 will return
 121 .B EINPROGRESS
 122 error.
 123 The user can then wait for various events via
 124 .BR poll (2)
 125 or
 126 .BR select (2).
 127 .TS
 128 tab(:) allbox;
 129 c s s
 130 l l l.
 131 I/O events
 132 Event:Poll flag:Occurrence
 133 Read:POLLIN:T{
 134 New data arrived.
 135 T}
 136 Read:POLLIN:T{
 137 A connection setup has been completed
 138 (for connection-oriented sockets)
 139 T}
 140 Read:POLLHUP:T{
 141 A disconnection request has been initiated by the other end.
 142 T}
 143 Read:POLLHUP:T{
 144 A connection is broken (only for connection-oriented protocols).
 145 When the socket is written
 146 .B SIGPIPE
 147 is also sent.
 148 T}
 149 Write:POLLOUT:T{
 150 Socket has enough send buffer space for writing new data.
 151 T}
 152 Read/Write:T{
 153 POLLIN|
 154 .br
 155 POLLOUT
 156 T}:T{
 157 An outgoing
 158 .BR connect (2)
 159 finished.
 160 T}
 161 Read/Write:POLLERR:An asynchronous error occurred.
 162 Read/Write:POLLHUP:The other end has shut down one direction.
 163 Exception:POLLPRI:T{
 164 Urgent data arrived.
 165 .B SIGURG
 166 is sent then.
 167 T}
 168 .\" FIXME . The following is not true currently:
 169 .\" It is no I/O event when the connection
 170 .\" is broken from the local end using
 171 .\" .BR shutdown (2)
 172 .\" or
 173 .\" .BR close (2).
 174 .TE
 175
 176 .PP
 177 An alternative to
 178 .BR poll (2)
 179 and
 180 .BR select (2)
 181 is to let the kernel inform the application about events
 182 via a
 183 .B SIGIO
 184 signal.
 185 For that the
 186 .B FASYNC
 187 flag must be set on a socket file descriptor via
 188 .BR fcntl (2)
 189 and a valid signal handler for
 190 .B SIGIO
 191 must be installed via
 192 .BR sigaction (2).
 193 See the
 194 .I Signals
 195 discussion below.
 196 .SS Socket Options
 197 These socket options can be set by using
 198 .BR setsockopt (2)
 199 and read with
 200 .BR getsockopt (2)
 201 with the socket level set to
 202 .B SOL_SOCKET
 203 for all sockets:
 204 .\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in
 205 .\" W R Stevens, UNPv1
 206 .TP
 207 .B SO_ACCEPTCONN
 208 Returns a value indicating whether or not this socket has been marked
 209 to accept connections with
 210 .BR listen (2).
 211 The value 0 indicates that this is not a listening socket,
 212 the value 1 indicates that this is a listening socket.
 213 Can only be read
 214 with
 215 .BR getsockopt (2).
 216 .TP
 217 .B SO_BINDTODEVICE
 218 Bind this socket to a particular device like \(lqeth0\(rq,
 219 as specified in the passed interface name.
 220 If the
 221 name is an empty string or the option length is zero, the socket device
 222 binding is removed.
 223 The passed option is a variable-length null terminated
 224 interface name string with the maximum size of
 225 .BR IFNAMSIZ .
 226 If a socket is bound to an interface,
 227 only packets received from that particular interface are processed by the
 228 socket.
 229 Note that this only works for some socket types, particularly
 230 .B AF_INET
 231 sockets.
 232 It is not supported for packet sockets (use normal
 233 .BR bind (8)
 234 there).
 235 .TP
 236 .B SO_BROADCAST
 237 Set or get the broadcast flag.
 238 When enabled, datagram sockets
 239 receive packets sent to a broadcast address and they are allowed to send
 240 packets to a broadcast address.
 241 This option has no effect on stream-oriented sockets.
 242 .TP
 243 .B SO_BSDCOMPAT
 244 Enable BSD bug-to-bug compatibility.
 245 This is used by the UDP protocol module in Linux 2.0 and 2.2.
 246 If enabled ICMP errors received for a UDP socket will not be passed
 247 to the user program.
 248 In later kernel versions, support for this option has been phased out:
 249 Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning
 250 (printk()) if a program uses this option.
 251 Linux 2.0 also enabled BSD bug-to-bug compatibility
 252 options (random header changing, skipping of the broadcast flag) for raw
 253 sockets with this option, but that was removed in Linux 2.2.
 254 .TP
 255 .B SO_DEBUG
 256 Enable socket debugging.
 257 Only allowed for processes with the
 258 .B CAP_NET_ADMIN
 259 capability or an effective user ID of 0.
 260 .TP
 261 .B SO_ERROR
 262 Get and clear the pending socket error.
 263 Only valid as a
 264 .BR getsockopt (2).
 265 Expects an integer.
 266 .TP
 267 .B SO_DONTROUTE
 268 Don't send via a gateway, only send to directly connected hosts.
 269 The same effect can be achieved by setting the
 270 .B MSG_DONTROUTE
 271 flag on a socket
 272 .BR send (2)
 273 operation.
 274 Expects an integer boolean flag.
 275 .TP
 276 .B SO_KEEPALIVE
 277 Enable sending of keep-alive messages on connection-oriented sockets.
 278 Expects an integer boolean flag.
 279 .TP
 280 .B SO_LINGER
 281 Sets or gets the
 282 .B SO_LINGER
 283 option.
 284 The argument is a
 285 .I linger
 286 structure.
 287 .sp
 288 .in +0.25i
 289 .nf
 290 struct linger {
 291     int l_onoff;    /* linger active */
 292     int l_linger;   /* how many seconds to linger for */
 293 };
 294 .fi
 295 .in -0.25i
 296 .IP
 297 When enabled, a
 298 .BR close (2)
 299 or
 300 .BR shutdown (2)
 301 will not return until all queued messages for the socket have been
 302 successfully sent or the linger timeout has been reached.
 303 Otherwise,
 304 the call returns immediately and the closing is done in the background.
 305 When the socket is closed as part of
 306 .BR exit (2),
 307 it always lingers in the background.
 308 .TP
 309 .B SO_OOBINLINE
 310 If this option is enabled,
 311 out-of-band data is directly placed into the receive data stream.
 312 Otherwise out-of-band data is only passed when the
 313 .B MSG_OOB
 314 flag is set during receiving.
 315 .\" don't document it because it can do too much harm.
 316 .\".B SO_NO_CHECK
 317 .TP
 318 .B SO_PASSCRED
 319 Enable or disable the receiving of the
 320 .B SCM_CREDENTIALS
 321 control message.
 322 For more information see
 323 .BR unix (7).
 324 .\" FIXME Document SO_PASSSEC, added in 2.6.18; there is some info
 325 .\" in the 2.6.18 ChangeLog
 326 .TP
 327 .B SO_PEERCRED
 328 Return the credentials of the foreign process connected to this socket.
 329 This is only possible for connected
 330 .B PF_UNIX
 331 stream sockets and
 332 .B PF_UNIX
 333 stream and datagram socket pairs created using
 334 .BR socketpair (2);
 335 see
 336 .BR unix (7).
 337 The returned credentials are those that were in effect at the time
 338 of the call to
 339 .BR connect (2)
 340 or
 341 .BR socketpair (2).
 342 Argument is a
 343 .I ucred
 344 structure.
 345 Only valid as a
 346 .BR getsockopt (2).
 347 .TP
 348 .B SO_PRIORITY
 349 Set the protocol-defined priority for all packets to be sent on
 350 this socket.
 351 Linux uses this value to order the networking queues:
 352 packets with a higher priority may be processed first depending
 353 on the selected device queueing discipline.
 354 For
 355 .BR ip (7),
 356 this also sets the IP type-of-service (TOS) field for outgoing packets.
 357 Setting a priority outside the range 0 to 6 requires the
 358 .B CAP_NET_ADMIN
 359 capability.
 360 .TP
 361 .B SO_RCVBUF
 362 Sets or gets the maximum socket receive buffer in bytes.
 363 The kernel doubles this value (to allow space for bookkeeping overhead)
 364 when it is set using
 365 .\" Most (all?) other implementations do not do this -- MTK, Dec 05
 366 .BR setsockopt (2),
 367 and this doubled value is returned by
 368 .BR getsockopt (2).
 369 The default value is set by the
 370 .I rmem_default
 371 sysctl and the maximum allowed value is set by the
 372 .I rmem_max
 373 sysctl.
 374 The minimum (doubled) value for this option is 256.
 375 .TP
 376 .BR SO_RCVBUFFORCE " (since Linux 2.6.14)"
 377 Using this socket option, a privileged
 378 .RB ( CAP_NET_ADMIN )
 379 process can perform the same task as
 380 .BR SO_RCVBUF ,
 381 but the
 382 .I rmem_max
 383 limit can be overridden.
 384 .TP
 385 .BR SO_RCVLOWAT " and " SO_SNDLOWAT
 386 Specify the minimum number of bytes in the buffer until the socket layer
 387 will pass the data to the protocol
 388 .RB ( SO_SNDLOWAT )
 389 or the user on receiving
 390 .RB ( SO_RCVLOWAT ).
 391 These two values are initialized to 1.
 392 .B SO_SNDLOWAT
 393 is not changeable on Linux
 394 .RB ( setsockopt
 395 fails with the error
 396 .BR ENOPROTOOPT ).
 397 .B SO_RCVLOWAT
 398 is changeable
 399 only since Linux 2.4.
 400 The
 401 .BR select (2)
 402 and
 403 .BR poll (2)
 404 system calls currently do not respect the
 405 .B SO_RCVLOWAT
 406 setting on Linux,
 407 and mark a socket readable when even a single byte of data is available.
 408 A subsequent read from the socket will block until
 409 .B SO_RCVLOWAT
 410 bytes are available.
 411 .\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2
 412 .\" Tested on kernel 2.6.14 -- mtk, 30 Nov 05
 413 .TP
 414 .BR SO_RCVTIMEO " and " SO_SNDTIMEO
 415 .\" Not implemented in 2.0.
 416 .\" Implemented in 2.1.11 for getsockopt: always return a zero struct.
 417 .\" Implemented in 2.3.41 for setsockopt, and actually used.
 418 Specify the receiving or sending timeouts until reporting an error.
 419 The parameter is a
 420 .IR "struct timeval" .
 421 If an input or output function blocks for this period of time, and
 422 data has been sent or received, the return value of that function
 423 will be the amount of data transferred; if no data has been transferred
 424 and the timeout has been reached then \-1 is returned with
 425 .I errno
 426 set to
 427 .B EAGAIN
 428 or
 429 .B EWOULDBLOCK
 430 .\" in fact to EAGAIN
 431 just as if the socket was specified to be nonblocking.
 432 If the timeout is set to zero (the default)
 433 then the operation will never timeout.
 434 Timeouts only have effect for system calls that perform socket I/O (e.g.,
 435 .BR read (2),
 436 .BR recvmsg (2),
 437 .BR send (2),
 438 .BR sendmsg (2));
 439 timeouts have no effect for
 440 .BR select (2),
 441 .BR poll (2),
 442 .BR epoll_wait (2),
 443 etc.
 444 .TP
 445 .B SO_REUSEADDR
 446 Indicates that the rules used in validating addresses supplied in a
 447 .BR bind (2)
 448 call should allow reuse of local addresses.
 449 For
 450 .B PF_INET
 451 sockets this
 452 means that a socket may bind, except when there
 453 is an active listening socket bound to the address.
 454 When the listening socket is bound to
 455 .B INADDR_ANY
 456 with a specific port then it is not possible
 457 to bind to this port for any local address.
 458 Argument is an integer boolean flag.
 459 .TP
 460 .B SO_SNDBUF
 461 Sets or gets the maximum socket send buffer in bytes.
 462 The kernel doubles this value (to allow space for bookkeeping overhead)
 463 when it is set using
 464 .\" Most (all?) other implementations do not do this -- MTK, Dec 05
 465 .BR setsockopt (2),
 466 and this doubled value is returned by
 467 .BR getsockopt (2).
 468 The default value is set by the
 469 .I wmem_default
 470 sysctl and the maximum allowed value is set by the
 471 .I wmem_max
 472 sysctl.
 473 The minimum (doubled) value for this option is 2048.
 474 .TP
 475 .BR SO_SNDBUFFORCE " (since Linux 2.6.14)"
 476 Using this socket option, a privileged
 477 .RB ( CAP_NET_ADMIN )
 478 process can perform the same task as
 479 .BR SO_SNDBUF ,
 480 but the
 481 .I wmem_max
 482 limit can be overridden.
 483 .TP
 484 .B SO_TIMESTAMP
 485 Enable or disable the receiving of the
 486 .B SO_TIMESTAMP
 487 control message.
 488 The timestamp control message is sent with level
 489 .B SOL_SOCKET
 490 and the
 491 .I cmsg_data
 492 field is a
 493 .I "struct timeval"
 494 indicating the
 495 reception time of the last packet passed to the user in this call.
 496 See
 497 .BR cmsg (3)
 498 for details on control messages.
 499 .TP
 500 .B SO_TYPE
 501 Gets the socket type as an integer (like
 502 .BR SOCK_STREAM ).
 503 Can only be read
 504 with
 505 .BR getsockopt (2).
 506 .SS Signals
 507 When writing onto a connection-oriented socket that has been shut down
 508 (by the local or the remote end)
 509 .B SIGPIPE
 510 is sent to the writing process and
 511 .B EPIPE
 512 is returned.
 513 The signal is not sent when the write call
 514 specified the
 515 .B MSG_NOSIGNAL
 516 flag.
 517 .PP
 518 When requested with the
 519 .B FIOSETOWN
 520 .BR fcntl (2)
 521 or
 522 .B SIOCSPGRP
 523 .BR ioctl (2),
 524 .B SIGIO
 525 is sent when an I/O event occurs.
 526 It is possible to use
 527 .BR poll (2)
 528 or
 529 .BR select (2)
 530 in the signal handler to find out which socket the event occurred on.
 531 An alternative (in Linux 2.2) is to set a realtime signal using the
 532 .B F_SETSIG
 533 .BR fcntl (2);
 534 the handler of the real time signal will be called with
 535 the file descriptor in the
 536 .I si_fd
 537 field of its
 538 .IR siginfo_t .
 539 See
 540 .BR fcntl (2)
 541 for more information.
 542 .PP
 543 Under some circumstances (e.g., multiple processes accessing a
 544 single socket), the condition that caused the
 545 .B SIGIO
 546 may have already disappeared when the process reacts to the signal.
 547 If this happens, the process should wait again because Linux
 548 will resend the signal later.
 549 .\" .SS Ancillary Messages
 550 .SS Sysctls
 551 The core socket networking sysctls can be accessed using the
 552 .I /proc/sys/net/core/*
 553 files or with the
 554 .BR sysctl (2)
 555 interface.
 556 .TP
 557 .I rmem_default
 558 contains the default setting in bytes of the socket receive buffer.
 559 .TP
 560 .I rmem_max
 561 contains the maximum socket receive buffer size in bytes which a user may
 562 set by using the
 563 .B SO_RCVBUF
 564 socket option.
 565 .TP
 566 .I wmem_default
 567 contains the default setting in bytes of the socket send buffer.
 568 .TP
 569 .I wmem_max
 570 contains the maximum socket send buffer size in bytes which a user may
 571 set by using the
 572 .B SO_SNDBUF
 573 socket option.
 574 .TP
 575 .BR message_cost " and " message_burst
 576 configure the token bucket filter used to load limit warning messages
 577 caused by external network events.
 578 .TP
 579 .I netdev_max_backlog
 580 Maximum number of packets in the global input queue.
 581 .TP
 582 .I optmem_max
 583 Maximum length of ancillary data and user control data like the iovecs
 584 per socket.
 585 .\" netdev_fastroute is not documented because it is experimental
 586 .SS Ioctls
 587 These operations can be accessed using
 588 .BR ioctl (2):
 589
 590 .in +0.25i
 591 .nf
 592 .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");"
 593 .fi
 594 .in -0.25i
 595 .TP
 596 .B SIOCGSTAMP
 597 Return a
 598 .I struct timeval
 599 with the receive timestamp of the last packet passed to the user.
 600 This is useful for accurate round trip time measurements.
 601 See
 602 .BR setitimer (2)
 603 for a description of
 604 .IR "struct timeval" .
 605 .\"
 606 This ioctl should only be used if the socket option
 607 .B SO_TIMESTAMP
 608 is not set on the socket.
 609 Otherwise, it returns the timestamp of the
 610 last packet that was received while
 611 .B SO_TIMESTAMP
 612 was not set, or it fails if no such packet has been received,
 613 (i.e.,
 614 .BR ioctl (2)
 615 returns \-1 with
 616 .I errno
 617 set to
 618 .BR ENOENT ).
 619 .TP
 620 .B SIOCSPGRP
 621 Set the process or process group to send
 622 .B SIGIO
 623 or
 624 .B SIGURG
 625 signals
 626 to when an
 627 asynchronous I/O operation has finished or urgent data is available.
 628 The argument is a pointer to a
 629 .IR pid_t .
 630 If the argument is positive, send the signals to that process.
 631 If the
 632 argument is negative, send the signals to the process group with the ID
 633 of the absolute value of the argument.
 634 The process may only choose itself or its own process group to receive
 635 signals unless it has the
 636 .B CAP_KILL
 637 capability or an effective UID of 0.
 638 .TP
 639 .B FIOASYNC
 640 Change the
 641 .B O_ASYNC
 642 flag to enable or disable asynchronous I/O mode of the socket.
 643 Asynchronous I/O mode means that the
 644 .B SIGIO
 645 signal or the signal set with
 646 .B F_SETSIG
 647 is raised when a new I/O event occurs.
 648 .IP
 649 Argument is an integer boolean flag.
 650 .\"
 651 .TP
 652 .B SIOCGPGRP
 653 Get the current process or process group that receives
 654 .B SIGIO
 655 or
 656 .B SIGURG
 657 signals,
 658 or 0
 659 when none is set.
 660 .PP
 661 Valid
 662 .BR fcntl (2)
 663 operations:
 664 .TP
 665 .B FIOGETOWN
 666 The same as the
 667 .B SIOCGPGRP
 668 .BR ioctl (2).
 669 .TP
 670 .B FIOSETOWN
 671 The same as the
 672 .B SIOCSPGRP
 673 .BR ioctl (2).
 674 .SH VERSIONS
 675 .B SO_BINDTODEVICE
 676 was introduced in Linux 2.0.30.
 677 .B SO_PASSCRED
 678 is new in Linux 2.2.
 679 The sysctls are new in Linux 2.2.
 680 .B SO_RCVTIMEO
 681 and
 682 .B SO_SNDTIMEO
 683 are supported since Linux 2.3.41.
 684 Earlier, timeouts were fixed to
 685 a protocol specific setting, and could not be read or written.
 686 .SH NOTES
 687 Linux assumes that half of the send/receive buffer is used for internal
 688 kernel structures; thus the sysctls are twice what can be observed
 689 on the wire.
 690
 691 Linux will only allow port re-use with the
 692 .B SO_REUSEADDR
 693 option
 694 when this option was set both in the previous program that performed a
 695 .BR bind (2)
 696 to the port and in the program that wants to re-use the port.
 697 This differs from some implementations (e.g., FreeBSD)
 698 where only the later program needs to set the
 699 .B SO_REUSEADDR
 700 option.
 701 Typically this difference is invisible, since, for example, a server
 702 program is designed to always set this option.
 703 .SH BUGS
 704 The
 705 .B CONFIG_FILTER
 706 socket options
 707 .B SO_ATTACH_FILTER
 708 and
 709 .B SO_DETACH_FILTER
 710 are
 711 not documented.
 712 The suggested interface to use them is via the libpcap
 713 library.
 714 .\" .SH AUTHORS
 715 .\" This man page was written by Andi Kleen.
 716 .SH "SEE ALSO"
 717 .BR getsockopt (2),
 718 .BR setsockopt (2),
 719 .BR socket (2),
 720 .BR capabilities (7),
 721 .BR ddp (7),
 722 .BR ip (7),
 723 .BR packet (7)