{ "content": [ { "type": "text", "text": "# socket (man)\n\n## NAME\n\nsocket - Linux socket interface\n\n## DESCRIPTION\n\nThis manual page describes the Linux networking socket layer user interface. The BSD compat‐\nible sockets are the uniform interface between the user process and the network protocol\nstacks in the kernel. The protocol modules are grouped into protocol families such as\nAFINET, AFIPX, and AFPACKET, and socket types such as SOCKSTREAM or SOCKDGRAM. See\nsocket(2) for more information on families and types.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (1 subsections)\n- **DESCRIPTION** (6 subsections)\n- **VERSIONS**\n- **NOTES**\n- **SEE ALSO**\n- **COLOPHON**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "socket", "section": "", "mode": "man", "summary": "socket - Linux socket interface", "synopsis": "", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "wireshark", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/wireshark/1/json" }, { "name": "bpf", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/bpf/2/json" }, { "name": "connect", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/connect/2/json" }, { "name": "getsockopt", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/getsockopt/2/json" }, { "name": "setsockopt", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/setsockopt/2/json" }, { "name": "pcap", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/pcap/3/json" }, { "name": "dressfamilies", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/dressfamilies/7/json" }, { "name": "capabilities", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/capabilities/7/json" }, { "name": "ddp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/ddp/7/json" }, { "name": "ip", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/ip/7/json" }, { "name": "ipv6", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/ipv6/7/json" }, { "name": "packet", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/packet/7/json" }, { "name": "tcp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/tcp/7/json" }, { "name": "udp", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/udp/7/json" }, { "name": "unix", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/unix/7/json" }, { "name": "tcpdump", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/tcpdump/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 1, "subsections": [ { "name": "#include ", "lines": 2 } ] }, { "name": "DESCRIPTION", "lines": 6, "subsections": [ { "name": "Socket-layer functions", "lines": 63 }, { "name": "Socket address structures", "lines": 22 }, { "name": "Socket options", "lines": 366 }, { "name": "Signals", "lines": 14 }, { "name": "/proc interfaces", "lines": 27 }, { "name": "Ioctls", "lines": 38 } ] }, { "name": "VERSIONS", "lines": 5, "subsections": [] }, { "name": "NOTES", "lines": 9, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] }, { "name": "COLOPHON", "lines": 7, "subsections": [] } ], "sections": { "NAME": { "content": "socket - Linux socket interface\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "#include ", "content": "sockfd = socket(int socketfamily, int sockettype, int protocol);\n" } ] }, "DESCRIPTION": { "content": "This manual page describes the Linux networking socket layer user interface. The BSD compat‐\nible sockets are the uniform interface between the user process and the network protocol\nstacks in the kernel. The protocol modules are grouped into protocol families such as\nAFINET, AFIPX, and AFPACKET, and socket types such as SOCKSTREAM or SOCKDGRAM. See\nsocket(2) for more information on families and types.\n", "subsections": [ { "name": "Socket-layer functions", "content": "These functions are used by the user process to send or receive packets and to do other\nsocket operations. For more information see their respective manual pages.\n\nsocket(2) creates a socket, connect(2) connects a socket to a remote socket address, the\nbind(2) function binds a socket to a local socket address, listen(2) tells the socket that\nnew connections shall be accepted, and accept(2) is used to get a new socket with a new in‐\ncoming connection. socketpair(2) returns two connected anonymous sockets (implemented only\nfor a few local families like AFUNIX)\n\nsend(2), sendto(2), and sendmsg(2) send data over a socket, and recv(2), recvfrom(2),\nrecvmsg(2) receive data from a socket. poll(2) and select(2) wait for arriving data or a\nreadiness to send data. In addition, the standard I/O operations like write(2), writev(2),\nsendfile(2), read(2), and readv(2) can be used to read and write data.\n\ngetsockname(2) returns the local socket address and getpeername(2) returns the remote socket\naddress. getsockopt(2) and setsockopt(2) are used to set or get socket layer or protocol op‐\ntions. ioctl(2) can be used to set or read some other options.\n\nclose(2) is used to close a socket. shutdown(2) closes parts of a full-duplex socket connec‐\ntion.\n\nSeeking, or calling pread(2) or pwrite(2) with a nonzero position is not supported on sock‐\nets.\n\nIt is possible to do nonblocking I/O on sockets by setting the ONONBLOCK flag on a socket\nfile descriptor using fcntl(2). Then all operations that would block will (usually) return\nwith EAGAIN (operation should be retried later); connect(2) will return EINPROGRESS error.\nThe user can then wait for various events via poll(2) or select(2).\n\n┌────────────────────────────────────────────────────────────────────┐\n│ I/O events │\n├───────────┬───────────┬────────────────────────────────────────────┤\n│Event │ Poll flag │ Occurrence │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Read │ POLLIN │ New data arrived. │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Read │ POLLIN │ A connection setup has been completed (for │\n│ │ │ connection-oriented sockets) │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Read │ POLLHUP │ A disconnection request has been initiated │\n│ │ │ by the other end. │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Read │ POLLHUP │ A connection is broken (only for connec‐ │\n│ │ │ tion-oriented protocols). When the socket │\n│ │ │ is written SIGPIPE is also sent. │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Write │ POLLOUT │ Socket has enough send buffer space for │\n│ │ │ writing new data. │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Read/Write │ POLLIN | │ An outgoing connect(2) finished. │\n│ │ POLLOUT │ │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Read/Write │ POLLERR │ An asynchronous error occurred. │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Read/Write │ POLLHUP │ The other end has shut down one direction. │\n├───────────┼───────────┼────────────────────────────────────────────┤\n│Exception │ POLLPRI │ Urgent data arrived. SIGURG is sent then. │\n└───────────┴───────────┴────────────────────────────────────────────┘\nAn alternative to poll(2) and select(2) is to let the kernel inform the application about\nevents via a SIGIO signal. For that the OASYNC flag must be set on a socket file descriptor\nvia fcntl(2) and a valid signal handler for SIGIO must be installed via sigaction(2). See\nthe Signals discussion below.\n" }, { "name": "Socket address structures", "content": "Each socket domain has its own format for socket addresses, with a domain-specific address\nstructure. Each of these structures begins with an integer \"family\" field (typed as safam‐\nilyt) that indicates the type of the address structure. This allows the various system\ncalls (e.g., connect(2), bind(2), accept(2), getsockname(2), getpeername(2)), which are\ngeneric to all socket domains, to determine the domain of a particular socket address.\n\nTo allow any type of socket address to be passed to interfaces in the sockets API, the type\nstruct sockaddr is defined. The purpose of this type is purely to allow casting of domain-\nspecific socket address types to a \"generic\" type, so as to avoid compiler warnings about\ntype mismatches in calls to the sockets API.\n\nIn addition, the sockets API provides the data type struct sockaddrstorage. This type is\nsuitable to accommodate all supported domain-specific socket address structures; it is large\nenough and is aligned properly. (In particular, it is large enough to hold IPv6 socket ad‐\ndresses.) The structure includes the following field, which can be used to identify the type\nof socket address actually stored in the structure:\n\nsafamilyt ssfamily;\n\nThe sockaddrstorage structure is useful in programs that must handle socket addresses in a\ngeneric way (e.g., programs that must deal with both IPv4 and IPv6 socket addresses).\n" }, { "name": "Socket options", "content": "The socket options listed below can be set by using setsockopt(2) and read with getsockopt(2)\nwith the socket level set to SOLSOCKET for all sockets. Unless otherwise noted, optval is a\npointer to an int.\n\nSOACCEPTCONN\nReturns a value indicating whether or not this socket has been marked to accept con‐\nnections with listen(2). The value 0 indicates that this is not a listening socket,\nthe value 1 indicates that this is a listening socket. This socket option is read-\nonly.\n\nSOATTACHFILTER (since Linux 2.2), SOATTACHBPF (since Linux 3.19)\nAttach a classic BPF (SOATTACHFILTER) or an extended BPF (SOATTACHBPF) program to\nthe socket for use as a filter of incoming packets. A packet will be dropped if the\nfilter program returns zero. If the filter program returns a nonzero value which is\nless than the packet's data length, the packet will be truncated to the length re‐\nturned. If the value returned by the filter is greater than or equal to the packet's\ndata length, the packet is allowed to proceed unmodified.\n\nThe argument for SOATTACHFILTER is a sockfprog structure, defined in :\n\nstruct sockfprog {\nunsigned short len;\nstruct sockfilter *filter;\n};\n\nThe argument for SOATTACHBPF is a file descriptor returned by the bpf(2) system call\nand must refer to a program of type BPFPROGTYPESOCKETFILTER.\n\nThese options may be set multiple times for a given socket, each time replacing the\nprevious filter program. The classic and extended versions may be called on the same\nsocket, but the previous filter will always be replaced such that a socket never has\nmore than one filter defined.\n\nBoth classic and extended BPF are explained in the kernel source file Documenta‐\ntion/networking/filter.txt\n\nSOATTACHREUSEPORTCBPF, SOATTACHREUSEPORTEBPF\nFor use with the SOREUSEPORT option, these options allow the user to set a classic\nBPF (SOATTACHREUSEPORTCBPF) or an extended BPF (SOATTACHREUSEPORTEBPF) program\nwhich defines how packets are assigned to the sockets in the reuseport group (that is,\nall sockets which have SOREUSEPORT set and are using the same local address to re‐\nceive packets).\n\nThe BPF program must return an index between 0 and N-1 representing the socket which\nshould receive the packet (where N is the number of sockets in the group). If the BPF\nprogram returns an invalid index, socket selection will fall back to the plain\nSOREUSEPORT mechanism.\n\nSockets are numbered in the order in which they are added to the group (that is, the\norder of bind(2) calls for UDP sockets or the order of listen(2) calls for TCP sock‐\nets). New sockets added to a reuseport group will inherit the BPF program. When a\nsocket is removed from a reuseport group (via close(2)), the last socket in the group\nwill be moved into the closed socket's position.\n\nThese options may be set repeatedly at any time on any socket in the group to replace\nthe current BPF program used by all sockets in the group.\n\nSOATTACHREUSEPORTCBPF takes the same argument type as SOATTACHFILTER and SOAT‐‐\nTACHREUSEPORTEBPF takes the same argument type as SOATTACHBPF.\n\nUDP support for this feature is available since Linux 4.5; TCP support is available\nsince Linux 4.6.\n\nSOBINDTODEVICE\nBind this socket to a particular device like “eth0”, as specified in the passed inter‐\nface name. If the name is an empty string or the option length is zero, the socket\ndevice binding is removed. The passed option is a variable-length null-terminated in‐\nterface name string with the maximum size of IFNAMSIZ. If a socket is bound to an in‐\nterface, only packets received from that particular interface are processed by the\nsocket. Note that this works only for some socket types, particularly AFINET sock‐\nets. It is not supported for packet sockets (use normal bind(2) there).\n\nBefore Linux 3.8, this socket option could be set, but could not retrieved with get‐‐\nsockopt(2). Since Linux 3.8, it is readable. The optlen argument should contain the\nbuffer size available to receive the device name and is recommended to be IFNAMSIZ\nbytes. The real device name length is reported back in the optlen argument.\n\nSOBROADCAST\nSet or get the broadcast flag. When enabled, datagram sockets are allowed to send\npackets to a broadcast address. This option has no effect on stream-oriented sockets.\n\nSOBSDCOMPAT\nEnable BSD bug-to-bug compatibility. This is used by the UDP protocol module in Linux\n2.0 and 2.2. If enabled, ICMP errors received for a UDP socket will not be passed to\nthe user program. In later kernel versions, support for this option has been phased\nout: Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning\n(printk()) if a program uses this option. Linux 2.0 also enabled BSD bug-to-bug com‐\npatibility options (random header changing, skipping of the broadcast flag) for raw\nsockets with this option, but that was removed in Linux 2.2.\n\nSODEBUG\nEnable socket debugging. Allowed only for processes with the CAPNETADMIN capability\nor an effective user ID of 0.\n\nSODETACHFILTER (since Linux 2.2), SODETACHBPF (since Linux 3.19)\nThese two options, which are synonyms, may be used to remove the classic or extended\nBPF program attached to a socket with either SOATTACHFILTER or SOATTACHBPF. The\noption value is ignored.\n\nSODOMAIN (since Linux 2.6.32)\nRetrieves the socket domain as an integer, returning a value such as AFINET6. See\nsocket(2) for details. This socket option is read-only.\n\nSOERROR\nGet and clear the pending socket error. This socket option is read-only. Expects an\ninteger.\n\nSODONTROUTE\nDon't send via a gateway, send only to directly connected hosts. The same effect can\nbe achieved by setting the MSGDONTROUTE flag on a socket send(2) operation. Expects\nan integer boolean flag.\n\nSOINCOMINGCPU (gettable since Linux 3.19, settable since Linux 4.4)\nSets or gets the CPU affinity of a socket. Expects an integer flag.\n\nint cpu = 1;\nsetsockopt(fd, SOLSOCKET, SOINCOMINGCPU, &cpu,\nsizeof(cpu));\n\nBecause all of the packets for a single stream (i.e., all packets for the same 4-tu‐\nple) arrive on the single RX queue that is associated with a particular CPU, the typi‐\ncal use case is to employ one listening process per RX queue, with the incoming flow\nbeing handled by a listener on the same CPU that is handling the RX queue. This pro‐\nvides optimal NUMA behavior and keeps CPU caches hot.\n\nSOINCOMINGNAPIID (gettable since Linux 4.12)\nReturns a system-level unique ID called NAPI ID that is associated with a RX queue on\nwhich the last packet associated with that socket is received.\n\nThis can be used by an application to split the incoming flows among worker threads\nbased on the RX queue on which the packets associated with the flows are received. It\nallows each worker thread to be associated with a NIC HW receive queue and service all\nthe connection requests received on that RX queue. This mapping between a app thread\nand a HW NIC queue streamlines the flow of data from the NIC to the application.\n\nSOKEEPALIVE\nEnable sending of keep-alive messages on connection-oriented sockets. Expects an in‐\nteger boolean flag.\n\nSOLINGER\nSets or gets the SOLINGER option. The argument is a linger structure.\n\nstruct linger {\nint lonoff; /* linger active */\nint llinger; /* how many seconds to linger for */\n};\n\nWhen enabled, a close(2) or shutdown(2) will not return until all queued messages for\nthe socket have been successfully sent or the linger timeout has been reached. Other‐\nwise, the call returns immediately and the closing is done in the background. When\nthe socket is closed as part of exit(2), it always lingers in the background.\n\nSOLOCKFILTER\nWhen set, this option will prevent changing the filters associated with the socket.\nThese filters include any set using the socket options SOATTACHFILTER, SOAT‐‐\nTACHBPF, SOATTACHREUSEPORTCBPF, and SOATTACHREUSEPORTEBPF.\n\nThe typical use case is for a privileged process to set up a raw socket (an operation\nthat requires the CAPNETRAW capability), apply a restrictive filter, set the\nSOLOCKFILTER option, and then either drop its privileges or pass the socket file de‐\nscriptor to an unprivileged process via a UNIX domain socket.\n\nOnce the SOLOCKFILTER option has been enabled, attempts to change or remove the fil‐\nter attached to a socket, or to disable the SOLOCKFILTER option will fail with the\nerror EPERM.\n\nSOMARK (since Linux 2.6.25)\nSet the mark for each packet sent through this socket (similar to the netfilter MARK\ntarget but socket-based). Changing the mark can be used for mark-based routing with‐\nout netfilter or for packet filtering. Setting this option requires the CAPNETADMIN\ncapability.\n\nSOOOBINLINE\nIf this option is enabled, out-of-band data is directly placed into the receive data\nstream. Otherwise, out-of-band data is passed only when the MSGOOB flag is set dur‐\ning receiving.\n\nSOPASSCRED\nEnable or disable the receiving of the SCMCREDENTIALS control message. For more in‐\nformation see unix(7).\n\nSOPASSSEC\nEnable or disable the receiving of the SCMSECURITY control message. For more infor‐\nmation see unix(7).\n\nSOPEEKOFF (since Linux 3.4)\nThis option, which is currently supported only for unix(7) sockets, sets the value of\nthe \"peek offset\" for the recv(2) system call when used with MSGPEEK flag.\n\nWhen this option is set to a negative value (it is set to -1 for all new sockets),\ntraditional behavior is provided: recv(2) with the MSGPEEK flag will peek data from\nthe front of the queue.\n\nWhen the option is set to a value greater than or equal to zero, then the next peek at\ndata queued in the socket will occur at the byte offset specified by the option value.\nAt the same time, the \"peek offset\" will be incremented by the number of bytes that\nwere peeked from the queue, so that a subsequent peek will return the next data in the\nqueue.\n\nIf data is removed from the front of the queue via a call to recv(2) (or similar)\nwithout the MSGPEEK flag, the \"peek offset\" will be decreased by the number of bytes\nremoved. In other words, receiving data without the MSGPEEK flag will cause the\n\"peek offset\" to be adjusted to maintain the correct relative position in the queued\ndata, so that a subsequent peek will retrieve the data that would have been retrieved\nhad the data not been removed.\n\nFor datagram sockets, if the \"peek offset\" points to the middle of a packet, the data\nreturned will be marked with the MSGTRUNC flag.\n\nThe following example serves to illustrate the use of SOPEEKOFF. Suppose a stream\nsocket has the following queued input data:\n\naabbccddeeff\n\nThe following sequence of recv(2) calls would have the effect noted in the comments:\n\nint ov = 4; // Set peek offset to 4\nsetsockopt(fd, SOLSOCKET, SOPEEKOFF, &ov, sizeof(ov));\n\nrecv(fd, buf, 2, MSGPEEK); // Peeks \"cc\"; offset set to 6\nrecv(fd, buf, 2, MSGPEEK); // Peeks \"dd\"; offset set to 8\nrecv(fd, buf, 2, 0); // Reads \"aa\"; offset set to 6\nrecv(fd, buf, 2, MSGPEEK); // Peeks \"ee\"; offset set to 8\n\nSOPEERCRED\nReturn the credentials of the peer process connected to this socket. For further de‐\ntails, see unix(7).\n\nSOPEERSEC (since Linux 2.6.2)\nReturn the security context of the peer socket connected to this socket. For further\ndetails, see unix(7) and ip(7).\n\nSOPRIORITY\nSet the protocol-defined priority for all packets to be sent on this socket. Linux\nuses this value to order the networking queues: packets with a higher priority may be\nprocessed first depending on the selected device queueing discipline. Setting a pri‐\nority outside the range 0 to 6 requires the CAPNETADMIN capability.\n\nSOPROTOCOL (since Linux 2.6.32)\nRetrieves the socket protocol as an integer, returning a value such as IPPROTOSCTP.\nSee socket(2) for details. This socket option is read-only.\n\nSORCVBUF\nSets or gets the maximum socket receive buffer in bytes. The kernel doubles this\nvalue (to allow space for bookkeeping overhead) when it is set using setsockopt(2),\nand this doubled value is returned by getsockopt(2). The default value is set by the\n/proc/sys/net/core/rmemdefault file, and the maximum allowed value is set by the\n/proc/sys/net/core/rmemmax file. The minimum (doubled) value for this option is 256.\n\nSORCVBUFFORCE (since Linux 2.6.14)\nUsing this socket option, a privileged (CAPNETADMIN) process can perform the same\ntask as SORCVBUF, but the rmemmax limit can be overridden.\n\nSORCVLOWAT and SOSNDLOWAT\nSpecify the minimum number of bytes in the buffer until the socket layer will pass the\ndata to the protocol (SOSNDLOWAT) or the user on receiving (SORCVLOWAT). These two\nvalues are initialized to 1. SOSNDLOWAT is not changeable on Linux (setsockopt(2)\nfails with the error ENOPROTOOPT). SORCVLOWAT is changeable only since Linux 2.4.\n\nBefore Linux 2.6.28 select(2), poll(2), and epoll(7) did not respect the SORCVLOWAT\nsetting on Linux, and indicated a socket as readable when even a single byte of data\nwas available. A subsequent read from the socket would then block until SORCVLOWAT\nbytes are available. Since Linux 2.6.28, select(2), poll(2), and epoll(7) indicate a\nsocket as readable only if at least SORCVLOWAT bytes are available.\n\nSORCVTIMEO and SOSNDTIMEO\nSpecify the receiving or sending timeouts until reporting an error. The argument is a\nstruct timeval. If an input or output function blocks for this period of time, and\ndata has been sent or received, the return value of that function will be the amount\nof data transferred; if no data has been transferred and the timeout has been reached,\nthen -1 is returned with errno set to EAGAIN or EWOULDBLOCK, or EINPROGRESS (for con‐‐\nnect(2)) just as if the socket was specified to be nonblocking. If the timeout is set\nto zero (the default), then the operation will never timeout. Timeouts only have ef‐\nfect for system calls that perform socket I/O (e.g., read(2), recvmsg(2), send(2),\nsendmsg(2)); timeouts have no effect for select(2), poll(2), epollwait(2), and so on.\n\nSOREUSEADDR\nIndicates that the rules used in validating addresses supplied in a bind(2) call\nshould allow reuse of local addresses. For AFINET sockets this means that a socket\nmay bind, except when there is an active listening socket bound to the address. When\nthe listening socket is bound to INADDRANY with a specific port then it is not possi‐\nble to bind to this port for any local address. Argument is an integer boolean flag.\n\nSOREUSEPORT (since Linux 3.9)\nPermits multiple AFINET or AFINET6 sockets to be bound to an identical socket ad‐\ndress. This option must be set on each socket (including the first socket) prior to\ncalling bind(2) on the socket. To prevent port hijacking, all of the processes bind‐\ning to the same address must have the same effective UID. This option can be employed\nwith both TCP and UDP sockets.\n\nFor TCP sockets, this option allows accept(2) load distribution in a multi-threaded\nserver to be improved by using a distinct listener socket for each thread. This pro‐\nvides improved load distribution as compared to traditional techniques such using a\nsingle accept(2)ing thread that distributes connections, or having multiple threads\nthat compete to accept(2) from the same socket.\n\nFor UDP sockets, the use of this option can provide better distribution of incoming\ndatagrams to multiple processes (or threads) as compared to the traditional technique\nof having multiple processes compete to receive datagrams on the same socket.\n\nSORXQOVFL (since Linux 2.6.33)\nIndicates that an unsigned 32-bit value ancillary message (cmsg) should be attached to\nreceived skbs indicating the number of packets dropped by the socket since its cre‐\nation.\n\nSOSELECTERRQUEUE (since Linux 3.10)\nWhen this option is set on a socket, an error condition on a socket causes notifica‐\ntion not only via the exceptfds set of select(2). Similarly, poll(2) also returns a\nPOLLPRI whenever an POLLERR event is returned.\n\nBackground: this option was added when waking up on an error condition occurred only\nvia the readfds and writefds sets of select(2). The option was added to allow moni‐\ntoring for error conditions via the exceptfds argument without simultaneously having\nto receive notifications (via readfds) for regular data that can be read from the\nsocket. After changes in Linux 4.16, the use of this flag to achieve the desired no‐\ntifications is no longer necessary. This option is nevertheless retained for back‐\nwards compatibility.\n\nSOSNDBUF\nSets or gets the maximum socket send buffer in bytes. The kernel doubles this value\n(to allow space for bookkeeping overhead) when it is set using setsockopt(2), and this\ndoubled value is returned by getsockopt(2). The default value is set by the\n/proc/sys/net/core/wmemdefault file and the maximum allowed value is set by the\n/proc/sys/net/core/wmemmax file. The minimum (doubled) value for this option is\n2048.\n\nSOSNDBUFFORCE (since Linux 2.6.14)\nUsing this socket option, a privileged (CAPNETADMIN) process can perform the same\ntask as SOSNDBUF, but the wmemmax limit can be overridden.\n\nSOTIMESTAMP\nEnable or disable the receiving of the SOTIMESTAMP control message. The timestamp\ncontrol message is sent with level SOLSOCKET and a cmsgtype of SCMTIMESTAMP. The\ncmsgdata field is a struct timeval indicating the reception time of the last packet\npassed to the user in this call. See cmsg(3) for details on control messages.\n\nSOTIMESTAMPNS (since Linux 2.6.22)\nEnable or disable the receiving of the SOTIMESTAMPNS control message. The timestamp\ncontrol message is sent with level SOLSOCKET and a cmsgtype of SCMTIMESTAMPNS. The\ncmsgdata field is a struct timespec indicating the reception time of the last packet\npassed to the user in this call. The clock used for the timestamp is CLOCKREALTIME.\nSee cmsg(3) for details on control messages.\n\nA socket cannot mix SOTIMESTAMP and SOTIMESTAMPNS: the two modes are mutually exclu‐\nsive.\n\nSOTYPE\nGets the socket type as an integer (e.g., SOCKSTREAM). This socket option is read-\nonly.\n\nSOBUSYPOLL (since Linux 3.11)\nSets the approximate time in microseconds to busy poll on a blocking receive when\nthere is no data. Increasing this value requires CAPNETADMIN. The default for this\noption is controlled by the /proc/sys/net/core/busyread file.\n\nThe value in the /proc/sys/net/core/busypoll file determines how long select(2) and\npoll(2) will busy poll when they operate on sockets with SOBUSYPOLL set and no\nevents to report are found.\n\nIn both cases, busy polling will only be done when the socket last received data from\na network device that supports this option.\n\nWhile busy polling may improve latency of some applications, care must be taken when\nusing it since this will increase both CPU utilization and power usage.\n" }, { "name": "Signals", "content": "When writing onto a connection-oriented socket that has been shut down (by the local or the\nremote end) SIGPIPE is sent to the writing process and EPIPE is returned. The signal is not\nsent when the write call specified the MSGNOSIGNAL flag.\n\nWhen requested with the FIOSETOWN fcntl(2) or SIOCSPGRP ioctl(2), SIGIO is sent when an I/O\nevent occurs. It is possible to use poll(2) or select(2) in the signal handler to find out\nwhich socket the event occurred on. An alternative (in Linux 2.2) is to set a real-time sig‐\nnal using the FSETSIG fcntl(2); the handler of the real time signal will be called with the\nfile descriptor in the sifd field of its siginfot. See fcntl(2) for more information.\n\nUnder some circumstances (e.g., multiple processes accessing a single socket), the condition\nthat caused the SIGIO may have already disappeared when the process reacts to the signal. If\nthis happens, the process should wait again because Linux will resend the signal later.\n" }, { "name": "/proc interfaces", "content": "The core socket networking parameters can be accessed via files in the directory\n/proc/sys/net/core/.\n\nrmemdefault\ncontains the default setting in bytes of the socket receive buffer.\n\nrmemmax\ncontains the maximum socket receive buffer size in bytes which a user may set by using\nthe SORCVBUF socket option.\n\nwmemdefault\ncontains the default setting in bytes of the socket send buffer.\n\nwmemmax\ncontains the maximum socket send buffer size in bytes which a user may set by using\nthe SOSNDBUF socket option.\n\nmessagecost and messageburst\nconfigure the token bucket filter used to load limit warning messages caused by exter‐\nnal network events.\n\nnetdevmaxbacklog\nMaximum number of packets in the global input queue.\n\noptmemmax\nMaximum length of ancillary data and user control data like the iovecs per socket.\n" }, { "name": "Ioctls", "content": "These operations can be accessed using ioctl(2):\n\nerror = ioctl(ipsocket, ioctltype, &valueresult);\n\nSIOCGSTAMP\nReturn a struct timeval with the receive timestamp of the last packet passed to the\nuser. This is useful for accurate round trip time measurements. See setitimer(2) for\na description of struct timeval. This ioctl should be used only if the socket options\nSOTIMESTAMP and SOTIMESTAMPNS are not set on the socket. Otherwise, it returns the\ntimestamp of the last packet that was received while SOTIMESTAMP and SOTIMESTAMPNS\nwere not set, or it fails if no such packet has been received, (i.e., ioctl(2) returns\n-1 with errno set to ENOENT).\n\nSIOCSPGRP\nSet the process or process group that is to receive SIGIO or SIGURG signals when I/O\nbecomes possible or urgent data is available. The argument is a pointer to a pidt.\nFor further details, see the description of FSETOWN in fcntl(2).\n\nFIOASYNC\nChange the OASYNC flag to enable or disable asynchronous I/O mode of the socket.\nAsynchronous I/O mode means that the SIGIO signal or the signal set with FSETSIG is\nraised when a new I/O event occurs.\n\nArgument is an integer boolean flag. (This operation is synonymous with the use of\nfcntl(2) to set the OASYNC flag.)\n\nSIOCGPGRP\nGet the current process or process group that receives SIGIO or SIGURG signals, or 0\nwhen none is set.\n\nValid fcntl(2) operations:\n\nFIOGETOWN\nThe same as the SIOCGPGRP ioctl(2).\n\nFIOSETOWN\nThe same as the SIOCSPGRP ioctl(2).\n" } ] }, "VERSIONS": { "content": "SOBINDTODEVICE was introduced in Linux 2.0.30. SOPASSCRED is new in Linux 2.2. The /proc\ninterfaces were introduced in Linux 2.2. SORCVTIMEO and SOSNDTIMEO are supported since\nLinux 2.3.41. Earlier, timeouts were fixed to a protocol-specific setting, and could not be\nread or written.\n", "subsections": [] }, "NOTES": { "content": "Linux assumes that half of the send/receive buffer is used for internal kernel structures;\nthus the values in the corresponding /proc files are twice what can be observed on the wire.\n\nLinux will allow port reuse only with the SOREUSEADDR option when this option was set both\nin the previous program that performed a bind(2) to the port and in the program that wants to\nreuse the port. This differs from some implementations (e.g., FreeBSD) where only the later\nprogram needs to set the SOREUSEADDR option. Typically this difference is invisible, since,\nfor example, a server program is designed to always set this option.\n", "subsections": [] }, "SEE ALSO": { "content": "wireshark(1), bpf(2), connect(2), getsockopt(2), setsockopt(2), socket(2), pcap(3), ad‐‐\ndressfamilies(7), capabilities(7), ddp(7), ip(7), ipv6(7), packet(7), tcp(7), udp(7),\nunix(7), tcpdump(8)\n", "subsections": [] }, "COLOPHON": { "content": "This page is part of release 5.10 of the Linux man-pages project. A description of the\nproject, information about reporting bugs, and the latest version of this page, can be found\nat https://www.kernel.org/doc/man-pages/.\n\n\n\nLinux 2020-08-13 SOCKET(7)", "subsections": [] } } } }