diff options
Diffstat (limited to 'man7/socket.7')
| -rw-r--r-- | man7/socket.7 | 264 |
1 files changed, 132 insertions, 132 deletions
diff --git a/man7/socket.7 b/man7/socket.7 index 3ff8fe51b..479dc5c1c 100644 --- a/man7/socket.7 +++ b/man7/socket.7 @@ -73,89 +73,89 @@ such as or .BR SOCK_DGRAM . See -.BR socket (2) +.MR socket 2 for more information on families and types. .SS Socket-layer functions These functions are used by the user process to send or receive packets and to do other socket operations. For more information, see their respective manual pages. .P -.BR socket (2) +.MR socket 2 creates a socket, -.BR connect (2) +.MR connect 2 connects a socket to a remote socket address, the -.BR bind (2) +.MR bind 2 function binds a socket to a local socket address, -.BR listen (2) +.MR listen 2 tells the socket that new connections shall be accepted, and -.BR accept (2) +.MR accept 2 is used to get a new socket with a new incoming connection. -.BR socketpair (2) +.MR socketpair 2 returns two connected anonymous sockets (implemented only for a few local families like .BR AF_UNIX ) .P -.BR send (2), -.BR sendto (2), +.MR send 2 , +.MR sendto 2 , and -.BR sendmsg (2) +.MR sendmsg 2 send data over a socket, and -.BR recv (2), -.BR recvfrom (2), -.BR recvmsg (2) +.MR recv 2 , +.MR recvfrom 2 , +.MR recvmsg 2 receive data from a socket. -.BR poll (2) +.MR poll 2 and -.BR select (2) +.MR select 2 wait for arriving data or a readiness to send data. In addition, the standard I/O operations like -.BR write (2), -.BR writev (2), -.BR sendfile (2), -.BR read (2), +.MR write 2 , +.MR writev 2 , +.MR sendfile 2 , +.MR read 2 , and -.BR readv (2) +.MR readv 2 can be used to read and write data. .P -.BR getsockname (2) +.MR getsockname 2 returns the local socket address and -.BR getpeername (2) +.MR getpeername 2 returns the remote socket address. -.BR getsockopt (2) +.MR getsockopt 2 and -.BR setsockopt (2) +.MR setsockopt 2 are used to set or get socket layer or protocol options. -.BR ioctl (2) +.MR ioctl 2 can be used to set or read some other options. .P -.BR close (2) +.MR close 2 is used to close a socket. -.BR shutdown (2) +.MR shutdown 2 closes parts of a full-duplex socket connection. .P Seeking, or calling -.BR pread (2) +.MR pread 2 or -.BR pwrite (2) +.MR pwrite 2 with a nonzero position is not supported on sockets. .P It is possible to do nonblocking I/O on sockets by setting the .B O_NONBLOCK flag on a socket file descriptor using -.BR fcntl (2). +.MR fcntl 2 . Then all operations that would block will (usually) return with .B EAGAIN (operation should be retried later); -.BR connect (2) +.MR connect 2 will return .B EINPROGRESS error. The user can then wait for various events via -.BR poll (2) +.MR poll 2 or -.BR select (2). +.MR select 2 . .TS tab(:) allbox; c s s @@ -187,7 +187,7 @@ POLLIN | POLLOUT T}:T{ An outgoing -.BR connect (2) +.MR connect 2 finished. T} Read/Write:POLLERR:T{ @@ -210,9 +210,9 @@ T} .TE .P An alternative to -.BR poll (2) +.MR poll 2 and -.BR select (2) +.MR select 2 is to let the kernel inform the application about events via a .B SIGIO @@ -220,11 +220,11 @@ signal. For that the .B O_ASYNC flag must be set on a socket file descriptor via -.BR fcntl (2) +.MR fcntl 2 and a valid signal handler for .B SIGIO must be installed via -.BR sigaction (2). +.MR sigaction 2 . See the .I Signals discussion below. @@ -237,11 +237,11 @@ integer "family" field (typed as that indicates the type of the address structure. This allows the various system calls (e.g., -.BR connect (2), -.BR bind (2), -.BR accept (2), -.BR getsockname (2), -.BR getpeername (2)), +.MR connect 2 , +.MR bind 2 , +.MR accept 2 , +.MR getsockname 2 , +.MR getpeername 2 ), which are generic to all socket domains, to determine the domain of a particular socket address. .P @@ -278,9 +278,9 @@ in a generic way (e.g., programs that must deal with both IPv4 and IPv6 socket addresses). .SS Socket options The socket options listed below can be set by using -.BR setsockopt (2) +.MR setsockopt 2 and read with -.BR getsockopt (2) +.MR getsockopt 2 with the socket level set to .B SOL_SOCKET for all sockets. @@ -298,7 +298,7 @@ is a pointer to an .B SO_ACCEPTCONN Returns a value indicating whether or not this socket has been marked to accept connections with -.BR listen (2). +.MR listen 2 . The value 0 indicates that this is not a listening socket, the value 1 indicates that this is a listening socket. This socket option is read-only. @@ -337,7 +337,7 @@ struct sock_fprog { The argument for .B SO_ATTACH_BPF is a file descriptor returned by the -.BR bpf (2) +.MR bpf 2 system call and must refer to a program of type .BR BPF_PROG_TYPE_SOCKET_FILTER . .IP @@ -374,13 +374,13 @@ mechanism. .IP Sockets are numbered in the order in which they are added to the group (that is, the order of -.BR bind (2) +.MR bind 2 calls for UDP sockets or the order of -.BR listen (2) +.MR listen 2 calls for TCP sockets). New sockets added to a reuseport group will inherit the BPF program. When a socket is removed from a reuseport group (via -.BR close (2)), +.MR close 2 ), the last socket in the group will be moved into the closed socket's position. .IP @@ -414,12 +414,12 @@ Note that this works only for some socket types, particularly .B AF_INET sockets. It is not supported for packet sockets (use normal -.BR bind (2) +.MR bind 2 there). .IP Before Linux 3.8, this socket option could be set, but could not retrieved with -.BR getsockopt (2). +.MR getsockopt 2 . Since Linux 3.8, it is readable. The .I optlen @@ -470,7 +470,7 @@ The option value is ignored. Retrieves the socket domain as an integer, returning a value such as .BR AF_INET6 . See -.BR socket (2) +.MR socket 2 for details. This socket option is read-only. .TP @@ -484,7 +484,7 @@ Don't send via a gateway, send only to directly connected hosts. The same effect can be achieved by setting the .B MSG_DONTROUTE flag on a socket -.BR send (2) +.MR send 2 operation. Expects an integer boolean flag. .TP @@ -566,15 +566,15 @@ struct linger { .in .IP When enabled, a -.BR close (2) +.MR close 2 or -.BR shutdown (2) +.MR shutdown 2 will not return until all queued messages for the socket have been successfully sent or the linger timeout has been reached. Otherwise, the call returns immediately and the closing is done in the background. When the socket is closed as part of -.BR exit (2), +.MR exit 2 , it always lingers in the background. .TP .B SO_LOCK_FILTER @@ -637,21 +637,21 @@ Enable or disable the receiving of the .B SCM_CREDENTIALS control message. For more information, see -.BR unix (7). +.MR unix 7 . .TP .B SO_PASSSEC Enable or disable the receiving of the .B SCM_SECURITY control message. For more information, see -.BR unix (7). +.MR unix 7 . .TP .BR SO_PEEK_OFF " (since Linux 3.4)" .\" commit ef64a54f6e558155b4f149bb10666b9e914b6c54 This option, which is currently supported only for -.BR unix (7) +.MR unix 7 sockets, sets the value of the "peek offset" for the -.BR recv (2) +.MR recv 2 system call when used with .B MSG_PEEK flag. @@ -659,7 +659,7 @@ flag. When this option is set to a negative value (it is set to \-1 for all new sockets), traditional behavior is provided: -.BR recv (2) +.MR recv 2 with the .B MSG_PEEK flag will peek data from the front of the queue. @@ -672,7 +672,7 @@ incremented by the number of bytes that were peeked from the queue, so that a subsequent peek will return the next data in the queue. .IP If data is removed from the front of the queue via a call to -.BR recv (2) +.MR recv 2 (or similar) without the .B MSG_PEEK flag, the "peek offset" will be decreased by the number of bytes removed. @@ -699,7 +699,7 @@ aabbccddeeff .in .IP The following sequence of -.BR recv (2) +.MR recv 2 calls would have the effect noted in the comments: .IP .in +4n @@ -717,14 +717,14 @@ recv(fd, buf, 2, MSG_PEEK); // Peeks "ee"; offset set to 8 .B SO_PEERCRED Return the credentials of the peer process connected to this socket. For further details, see -.BR unix (7). +.MR unix 7 . .TP .BR SO_PEERSEC " (since Linux 2.6.2)" Return the security context of the peer socket connected to this socket. For further details, see -.BR unix (7) +.MR unix 7 and -.BR ip (7). +.MR ip 7 . .TP .B SO_PRIORITY Set the protocol-defined priority for all packets to be sent on @@ -743,7 +743,7 @@ capability. Retrieves the socket protocol as an integer, returning a value such as .BR IPPROTO_SCTP . See -.BR socket (2) +.MR socket 2 for details. This socket option is read-only. .TP @@ -752,9 +752,9 @@ Sets or gets the maximum socket receive buffer in bytes. The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using .\" Most (all?) other implementations do not do this -- MTK, Dec 05 -.BR setsockopt (2), +.MR setsockopt 2 , and this doubled value is returned by -.BR getsockopt (2). +.MR getsockopt 2 . .\" The following thread on LMKL is quite informative: .\" getsockopt/setsockopt with SO_RCVBUF and SO_SNDBUF "non-standard" behavior .\" 17 July 2012 @@ -793,10 +793,10 @@ only since Linux 2.4. .IP Before Linux 2.6.28 .\" Tested on kernel 2.6.14 -- mtk, 30 Nov 05 -.BR select (2), -.BR poll (2), +.MR select 2 , +.MR poll 2 , and -.BR epoll (7) +.MR epoll 7 did not respect the .B SO_RCVLOWAT setting on Linux, @@ -807,10 +807,10 @@ A subsequent read from the socket would then block until bytes are available. Since Linux 2.6.28, .\" commit c7004482e8dcb7c3c72666395cfa98a216a4fb70 -.BR select (2), -.BR poll (2), +.MR select 2 , +.MR poll 2 , and -.BR epoll (7) +.MR epoll 7 indicate a socket as readable only if at least .B SO_RCVLOWAT bytes are available. @@ -835,28 +835,28 @@ or or .B EINPROGRESS (for -.BR connect (2)) +.MR connect 2 ) just as if the socket was specified to be nonblocking. If the timeout is set to zero (the default), then the operation will never timeout. Timeouts only have effect for system calls that perform socket I/O (e.g., -.BR accept (2), -.BR connect (2), -.BR read (2), -.BR recvmsg (2), -.BR send (2), -.BR sendmsg (2)); +.MR accept 2 , +.MR connect 2 , +.MR read 2 , +.MR recvmsg 2 , +.MR send 2 , +.MR sendmsg 2 ); timeouts have no effect for -.BR select (2), -.BR poll (2), -.BR epoll_wait (2), +.MR select 2 , +.MR poll 2 , +.MR epoll_wait 2 , and so on. .TP .B SO_REUSEADDR .\" commit c617f398edd4db2b8567a28e899a88f8f574798d .\" https://lwn.net/Articles/542629/ Indicates that the rules used in validating addresses supplied in a -.BR bind (2) +.MR bind 2 call should allow reuse of local addresses. For .B AF_INET @@ -877,7 +877,7 @@ or sockets to be bound to an identical socket address. This option must be set on each socket (including the first socket) prior to calling -.BR bind (2) +.MR bind 2 on the socket. To prevent port hijacking, all of the processes binding to the same address must have the same @@ -885,15 +885,15 @@ effective UID. This option can be employed with both TCP and UDP sockets. .IP For TCP sockets, this option allows -.BR accept (2) +.MR accept 2 load distribution in a multi-threaded server to be improved by using a distinct listener socket for each thread. This provides improved load distribution as compared to traditional techniques such using a single -.BR accept (2)ing +.MR accept 2 ing thread that distributes connections, or having multiple threads that compete to -.BR accept (2) +.MR accept 2 from the same socket. .IP For UDP sockets, @@ -915,9 +915,9 @@ When this option is set on a socket, an error condition on a socket causes notification not only via the .I exceptfds set of -.BR select (2). +.MR select 2 . Similarly, -.BR poll (2) +.MR poll 2 also returns a .B POLLPRI whenever an @@ -931,7 +931,7 @@ occurred only via the and .I writefds sets of -.BR select (2). +.MR select 2 . The option was added to allow monitoring for error conditions via the .I exceptfds argument without simultaneously having to receive notifications (via @@ -950,9 +950,9 @@ The kernel doubles this value (to allow space for bookkeeping overhead) when it is set using .\" Most (all?) other implementations do not do this -- MTK, Dec 05 .\" See also the comment to SO_RCVBUF (17 Jul 2012 LKML mail) -.BR setsockopt (2), +.MR setsockopt 2 , and this doubled value is returned by -.BR getsockopt (2). +.MR getsockopt 2 . The default value is set by the .I /proc/sys/net/core/wmem_default file and the maximum allowed value is set by the @@ -986,7 +986,7 @@ field is a indicating the reception time of the last packet passed to the user in this call. See -.BR cmsg (3) +.MR cmsg 3 for details on control messages. .TP .BR SO_TIMESTAMPNS " (since Linux 2.6.22)" @@ -1009,7 +1009,7 @@ reception time of the last packet passed to the user in this call. The clock used for the timestamp is .BR CLOCK_REALTIME . See -.BR cmsg (3) +.MR cmsg 3 for details on control messages. .IP A socket cannot mix @@ -1035,9 +1035,9 @@ file. The value in the .I /proc/sys/net/core/busy_poll file determines how long -.BR select (2) +.MR select 2 and -.BR poll (2) +.MR poll 2 will busy poll when they operate on sockets with .B SO_BUSY_POLL set and no events to report are found. @@ -1063,27 +1063,27 @@ flag. .P When requested with the .B FIOSETOWN -.BR fcntl (2) +.MR fcntl 2 or .B SIOCSPGRP -.BR ioctl (2), +.MR ioctl 2 , .B SIGIO is sent when an I/O event occurs. It is possible to use -.BR poll (2) +.MR poll 2 or -.BR select (2) +.MR select 2 in the signal handler to find out which socket the event occurred on. An alternative (in Linux 2.2) is to set a real-time signal using the .B F_SETSIG -.BR fcntl (2); +.MR fcntl 2 ; the handler of the real time signal will be called with the file descriptor in the .I si_fd field of its .IR siginfo_t . See -.BR fcntl (2) +.MR fcntl 2 for more information. .P Under some circumstances (e.g., multiple processes accessing a @@ -1129,7 +1129,7 @@ per socket. .\" netdev_fastroute is not documented because it is experimental .SS Ioctls These operations can be accessed using -.BR ioctl (2): +.MR ioctl 2 : .P .in +4n .EX @@ -1143,7 +1143,7 @@ Return a with the receive timestamp of the last packet passed to the user. This is useful for accurate round trip time measurements. See -.BR setitimer (2) +.MR setitimer 2 for a description of .IR "struct timeval" . .\" @@ -1159,7 +1159,7 @@ and .B SO_TIMESTAMPNS were not set, or it fails if no such packet has been received, (i.e., -.BR ioctl (2) +.MR ioctl 2 returns \-1 with .I errno set to @@ -1176,7 +1176,7 @@ The argument is a pointer to a For further details, see the description of .B F_SETOWN in -.BR fcntl (2). +.MR fcntl 2 . .TP .B FIOASYNC Change the @@ -1190,7 +1190,7 @@ is raised when a new I/O event occurs. .IP Argument is an integer boolean flag. (This operation is synonymous with the use of -.BR fcntl (2) +.MR fcntl 2 to set the .B O_ASYNC flag.) @@ -1206,18 +1206,18 @@ or 0 when none is set. .P Valid -.BR fcntl (2) +.MR fcntl 2 operations: .TP .B FIOGETOWN The same as the .B SIOCGPGRP -.BR ioctl (2). +.MR ioctl 2 . .TP .B FIOSETOWN The same as the .B SIOCSPGRP -.BR ioctl (2). +.MR ioctl 2 . .SH VERSIONS .B SO_BINDTODEVICE was introduced in Linux 2.0.30. @@ -1242,7 +1242,7 @@ Linux will allow port reuse only with the .B SO_REUSEADDR option when this option was set both in the previous program that performed a -.BR bind (2) +.MR bind 2 to the port and in the program that wants to reuse the port. This differs from some implementations (e.g., FreeBSD) where only the later program needs to set the @@ -1253,20 +1253,20 @@ program is designed to always set this option. .\" .SH AUTHORS .\" This man page was written by Andi Kleen. .SH SEE ALSO -.BR wireshark (1), -.BR bpf (2), -.BR connect (2), -.BR getsockopt (2), -.BR setsockopt (2), -.BR socket (2), -.BR pcap (3), -.BR address_families (7), -.BR capabilities (7), -.BR ddp (7), -.BR ip (7), -.BR ipv6 (7), -.BR packet (7), -.BR tcp (7), -.BR udp (7), -.BR unix (7), -.BR tcpdump (8) +.MR wireshark 1 , +.MR bpf 2 , +.MR connect 2 , +.MR getsockopt 2 , +.MR setsockopt 2 , +.MR socket 2 , +.MR pcap 3 , +.MR address_families 7 , +.MR capabilities 7 , +.MR ddp 7 , +.MR ip 7 , +.MR ipv6 7 , +.MR packet 7 , +.MR tcp 7 , +.MR udp 7 , +.MR unix 7 , +.MR tcpdump 8 |