Import of man-pages 1.70man-pages-1.70

author: Michael Kerrisk <mtk.manpages@gmail.com> 2004-11-03 13:51:07 +0000
committer: Michael Kerrisk <mtk.manpages@gmail.com> 2004-11-03 13:51:07 +0000
commit: fea681dafb1363a154b7fc6d59baa83d2a9ebc5c (patch)
tree: 8ea275c0f242af739617d0afc3e1b16c4eff3dc2 /man7/socket.7
download: man-pages-fea681dafb1363a154b7fc6d59baa83d2a9ebc5c.tar.gz
1 files changed, 588 insertions, 0 deletions
diff --git a/man7/socket.7 b/man7/socket.7
new file mode 100644
index 0000000000..890d90850c
--- /dev/null
+++ b/man7/socket.7
@@ -0,0 +1,588 @@
+'\" t
+.\" Don't change the first line, it tells man that we need tbl.
+.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
+.\" and copyright (c) 1999 Matthew Wilcox. 
+.\" Permission is granted to distribute possibly modified copies
+.\" of this page provided the header is included verbatim,
+.\" and in case of nontrivial modification author and date
+.\" of the modification is added to the header.
+.\"
+.\" 2002-10-30, Michael Kerrisk, mtk16@ext.canterbury.ac.nz
+.\"	Added description of SO_ACCEPTCONN
+.\" 2004-05-20, aeb, added SO_RCVTIMEO/SO_SNDTIMEO text.
+.\" Modified, 27 May 2004, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
+.\"     Added notes on capability requirements
+.\"	A few small grammar fixes
+.\" 
+.\" FIXME: probably all PF_* shouls be AF_* in this page, since
+.\"        POSIX only specifies the latter values.
+.\"
+.TH SOCKET 7 2004-05-27 "Linux 2.6.6" "Linux Programmer's Manual"
+.SH NAME
+socket - Linux socket interface
+.SH SYNOPSIS
+.B #include <sys/socket.h>
+.br
+.IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol );
+
+.SH DESCRIPTION
+This manual page describes the Linux networking socket layer user 
+interface. The BSD compatible sockets
+are the uniform interface
+between the user process and the network protocol stacks in the kernel.
+The protocol modules are grouped into 
+.I protocol families
+like
+.BR PF_INET ", " PF_IPX ", " PF_PACKET
+and
+.I socket types
+like
+.B SOCK_STREAM
+or
+.BR SOCK_DGRAM .
+See 
+.BR socket (2)
+for more information on families and types.
+
+.SH "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.
+
+.BR socket (2)
+creates a socket,
+.BR connect (2)
+connects a socket to a remote socket address,
+the 
+.BR bind (2)
+function binds a socket to a local socket address,
+.BR listen (2)
+tells the socket that new connections shall be accepted, and
+.BR accept (2)
+is used to get a new socket with a new incoming connection.
+.BR socketpair (2)
+returns two connected anonymous sockets (only implemented for a few
+local families like
+.BR PF_UNIX )
+.PP
+.BR send (2),
+.BR sendto (2),
+and
+.BR sendmsg (2)
+send data over a socket, and
+.BR recv (2),
+.BR recvfrom (2),
+.BR recvmsg (2)
+receive data from a socket.
+.BR poll (2)
+and
+.BR 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),
+and  
+.BR readv (2) 
+can be used to read and write data.
+.PP
+.BR getsockname (2)
+returns the local socket address and
+.BR getpeername (2)
+returns the remote socket address.
+.BR getsockopt (2)
+and
+.BR setsockopt (2)
+are used to set or get socket layer or protocol options. 
+.BR ioctl (2)
+can be used to set or read some other options.
+.PP
+.BR close (2)
+is used to close a socket.
+.BR shutdown (2)
+closes parts of a full duplex socket connection. 
+.PP
+Seeking, or calling 
+.BR pread (2) 
+or 
+.BR pwrite (2)
+with a non-zero position is not supported on sockets.
+.PP
+It is possible to do non-blocking IO on sockets by setting the 
+.B O_NONBLOCK
+flag on a socket file descriptor using
+.BR fcntl (2).
+Then all operations that would block will (usually)
+return with
+.B EAGAIN 
+(operation should be retried later);
+.BR connect (2) 
+will return 
+.B EINPROGRESS
+error. 
+The user can then wait for various events via
+.BR poll (2)
+or
+.BR select (2). 
+.PP
+.TS
+tab(:) allbox;
+c s s
+l l l.
+I/O events
+Event:Poll flag:Occurrence
+Read:POLLIN:T{
+New data arrived. 
+T}
+Read:POLLIN:T{
+A connection setup has been completed
+(for connection-oriented sockets)
+T}
+Read:POLLHUP:T{
+A disconnection request has been initiated by the other end. 
+T}
+Read:POLLHUP:T{
+A connection is broken (only for connection-oriented protocols). 
+When the socket is written
+.B SIGPIPE 
+is also sent.
+T}
+Write:POLLOUT:T{
+Socket has enough send buffer space for writing new data.
+T}
+Read/Write:T{
+POLLIN|
+.br
+POLLOUT
+T}:T{
+An outgoing
+.BR connect (2)
+finished.
+T}
+Read/Write:POLLERR:An asynchronous error occurred.
+Read/Write:POLLHUP:The other end has shut down one direction.
+Exception:POLLPRI:T{
+Urgent data arrived.  
+.B SIGURG
+is sent then.
+T}
+.\" XXX not true currently
+.\" It is no I/O event when the connection
+.\" is broken from the local end using 
+.\" .BR shutdown (2)
+.\" or 
+.\" .BR close (2)
+.\" .
+.TE
+
+.PP
+An alternative to poll/select  
+is to let the kernel inform the application about events
+via a
+.B SIGIO
+signal. For that the
+.B FASYNC
+flag must be set on a socket file descriptor 
+via
+.BR fcntl (2)
+and a valid signal handler for 
+.B SIGIO
+must be installed via 
+.BR sigaction (2). 
+See the
+.I SIGNALS
+discussion below.
+.SH "SOCKET OPTIONS"
+These socket options can be set by using
+.BR setsockopt (2)
+and read with 
+.BR getsockopt (2)
+with the socket level set to 
+.B SOL_SOCKET 
+for all sockets:
+.TP
+.B SO_KEEPALIVE
+Enable sending of keep-alive messages on connection-oriented sockets. Expects
+an integer boolean flag. 
+.TP
+.B SO_OOBINLINE
+If this option is enabled, out-of-band data is directly placed into the receive
+data stream. Otherwise out-of-band data is only passed when the 
+.B MSG_OOB 
+flag is set during receiving. 
+.\" don't document it because it can do too much harm.
+.\".B SO_NO_CHECK
+.TP
+.BR SO_RCVLOWAT " and " SO_SNDLOWAT
+Specify the minimum number of bytes in the buffer until the socket layer
+will pass the data to the protocol 
+.RB ( SO_SNDLOWAT ) 
+or the user on receiving 
+.RB ( SO_RCVLOWAT ).
+These two values are not changeable in Linux and their argument size
+is always fixed
+to 1 byte. 
+.B getsockopt 
+is able to read them; 
+.B setsockopt 
+will always return
+.BR ENOPROTOOPT .  
+.TP
+.BR SO_RCVTIMEO " and " SO_SNDTIMEO
+.\" Not implemented in 2.0.
+.\" Implemented in 2.1.11 for getsockopt: always return a zero struct.
+.\" Implemented in 2.3.41 for setsockopt, and actually used.
+Specify the receiving or sending timeouts until reporting an error.
+The parameter is a struct timeval.
+If an input or output function blocks for this period of time, and
+data has been sent or received, the return value of that function
+will be the amount of data transferred; if no data has been transferred
+and the timeout has been reached then -1 is returned with
+.I errno
+set to EAGAIN or EWOULDBLOCK
+.\" in fact to EAGAIN
+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.
+.TP
+.B SO_BSDCOMPAT
+Enable BSD bug-to-bug compatibility. This is used only by the UDP
+protocol module and scheduled to be removed in future.  
+If enabled ICMP errors received for a UDP socket will not be passed
+to the user program. Linux 2.0 also enabled BSD bug-to-bug compatibility 
+options (random header changing, skipping of the broadcast flag) for raw
+sockets with this option, but that has been removed in Linux 2.2. It is
+better to fix the user programs than to enable this flag.
+.TP
+.B SO_PASSCRED
+Enable or disable the receiving of the
+.B SCM_CREDENTIALS
+control message. For more information see 
+.BR unix (7). 
+.TP
+.B SO_PEERCRED
+Return the credentials of the foreign process connected to this socket. 
+Only useful for 
+.B PF_UNIX 
+sockets; see 
+.BR unix (7). 
+Argument is a
+.B ucred 
+structure. Only valid as a 
+.BR getsockopt .
+.TP
+.B SO_BINDTODEVICE
+Bind this socket to a particular device like \(lqeth0\(rq,
+as specified in the passed interface name. If the
+name is an empty string or the option length is zero, the socket device
+binding is removed. The passed option is a variable-length null terminated
+interface name string with the maximum size of 
+.BR IFNAMSIZ .
+If a socket is bound to an interface,
+only packets received from that particular interface are processed by the 
+socket. Note that this only works for some socket types, particularly
+.B AF_INET
+sockets. It is not supported for packet sockets (use normal 
+.BR bind (8)
+there).
+.TP
+.B SO_DEBUG 
+Enable socket debugging. Only allowed for processes with the
+.B CAP_NET_ADMIN
+capability or an effective user id of 0.
+.TP
+.B SO_REUSEADDR
+Indicates that the rules used in validating addresses supplied in a 
+.BR bind (2) 
+call should allow reuse of local addresses. For
+.B PF_INET
+sockets this
+means that a socket may bind, except when there
+is an active listening socket bound to the address.
+When the listening socket is bound to
+.B INADDR_ANY
+with a specific port then it is not possible
+to bind to this port for any local address.
+.TP
+.B SO_TYPE
+Gets the socket type as an integer (like 
+.BR SOCK_STREAM ). 
+Can only be read
+with 
+.BR getsockopt . 
+.\" SO_ACCEPTCONN is in SUSv3, and its origin is explained in 
+.\" W R Stevens, UNPv1
+.TP
+.B SO_ACCEPTCONN
+Returns a value indicating whether or not this socket has been marked
+to accept connections with
+.BR listen ().
+The value 0 indicates that this is not a listening socket,
+the value 1 indicates that this is a listening socket.
+Can only be read
+with 
+.BR getsockopt . 
+.TP
+.B SO_DONTROUTE
+Don't send via a gateway, only send to directly connected hosts.
+The same effect can be achieved by setting the 
+.B MSG_DONTROUTE
+flag on a socket 
+.BR send (2)
+operation. Expects an integer boolean flag. 
+.TP
+.B SO_BROADCAST
+Set or get the broadcast flag. When enabled, datagram sockets
+receive packets sent to a broadcast address and they are allowed to send 
+packets to a broadcast address.
+This option has no effect on stream-oriented sockets.
+.TP
+.B SO_SNDBUF 
+Sets or gets the maximum socket send buffer in bytes.  The default value is set
+by the 
+.B wmem_default 
+sysctl and the maximum allowed value is set by the 
+.B wmem_max
+sysctl.   
+.TP
+.B SO_RCVBUF
+Sets or gets the maximum socket receive buffer in bytes. The default value is
+set by the 
+.B rmem_default 
+sysctl and the maximum allowed value is set by the 
+.B rmem_max
+sysctl.   
+.TP
+.B SO_LINGER
+Sets or gets the 
+.B SO_LINGER 
+option. The argument is a 
+.B linger 
+structure.
+.PP
+.RS
+.nf
+.ta 4n 10n 22n
+struct linger {
+	int	l_onoff;	/* linger active */
+	int	l_linger;	/* how many seconds to linger for */
+};
+.ta
+.fi
+.RE
+.IP
+When enabled, a 
+.BR close (2)
+or
+.BR 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),
+it always lingers in the background.
+.TP
+.B SO_PRIORITY
+Set the protocol-defined priority for all packets to be sent on this socket.
+Linux uses this value to order the networking queues: packets with a higher
+priority may be processed first depending on the selected device queueing 
+discipline. For
+.BR ip (7),
+this also sets the IP type-of-service (TOS) field for outgoing packets.  
+Setting a priority outside the range 0 to 6 requires the
+.B CAP_NET_ADMIN
+capability.
+.TP
+.B SO_ERROR
+Get and clear the pending socket error. Only valid as a 
+.BR getsockopt .
+Expects an integer. 
+.SH SIGNALS
+When writing onto a connection-oriented socket that has been shut down
+(by the local or the remote end) 
+.B SIGPIPE
+is sent to the writing process and 
+.B EPIPE
+is returned. 
+The signal is not sent when the write call
+specified the
+.B MSG_NOSIGNAL 
+flag.
+.PP
+When requested with the 
+.B FIOSETOWN 
+fcntl or 
+.B SIOCSPGRP 
+ioctl,
+.B SIGIO 
+is sent when an I/O event occurs. It is possible to use
+.BR poll (2)
+or 
+.BR 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 realtime signal using the
+.B F_SETSIG
+fcntl; 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)
+for more information.
+.PP
+Under some circumstances (e.g. multiple processes accessing a single socket),
+the condition that caused the
+.B SIGIO
+may have already disappeared when the process reacts to the signal.
+If this happens, the process should wait again because Linux will resend the
+signal later.
+.\" .SH ANCILLARY MESSAGES
+.SH SYSCTLS
+The core socket networking sysctls can be accessed using the 
+.B /proc/sys/net/core/* 
+files or with the 
+.BR sysctl (2) 
+interface. 
+.TP
+.B rmem_default
+contains the default setting in bytes of the socket receive buffer.
+.TP
+.B rmem_max
+contains the maximum socket receive buffer size in bytes which a user may
+set by using the 
+.B SO_RCVBUF
+socket option. 
+.TP
+.B wmem_default
+contains the default setting in bytes of the socket send buffer.
+.TP
+.B wmem_max
+contains the maximum socket send buffer size in bytes which a user may
+set by using the 
+.B SO_SNDBUF
+socket option. 
+.TP
+.BR message_cost " and " message_burst 
+configure the token bucket filter used to load limit warning messages
+caused by external network events.
+.TP
+.B netdev_max_backlog 
+Maximum number of packets in the global input queue.
+.TP
+.B optmem_max
+Maximum length of ancillary data and user control data like the iovecs 
+per socket.  
+.\" netdev_fastroute is not documented because it is experimental
+.SH IOCTLS
+These ioctls can be accessed using 
+.BR ioctl (2):
+
+.RS
+.nf
+.IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");"
+.fi
+.RE
+
+.TP
+.B SIOCGSTAMP
+Return a 
+.B struct timeval 
+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) 
+for a description of 
+.BR "struct timeval" .
+.\"
+.TP
+.BR SIOCSPGRP
+Set the process or process group to send 
+.B SIGIO
+or 
+.B SIGURG
+signals 
+to when an
+asynchronous I/O operation has finished or urgent data is available.
+The argument is a pointer to a 
+.BR pid_t . 
+If the argument is positive, send the signals to that process.  If the
+argument is negative, send the signals to the process group with the id
+of the absolute value of the argument.
+The process may only choose itself or its own process group to receive
+signals unless it has the
+.B CAP_KILL
+capability or an effective UID of 0.
+.TP
+.B FIOASYNC
+Change the
+.B O_ASYNC
+flag to enable or disable asynchronous IO mode of the socket. Asynchronous IO
+mode means that the
+.B SIGIO 
+signal or the signal set with 
+.B F_SETSIG
+is raised when a new I/O event occurs.
+.IP
+Argument is an integer boolean flag. 
+.\"
+.TP
+.BR SIOCGPGRP
+Get the current process or process group that receives
+.B SIGIO 
+or 
+.B SIGURG
+signals, 
+or 0
+when none is set.  
+.PP
+Valid fcntls:
+.TP
+.BR FIOGETOWN 
+The same as the SIOCGPGRP ioctl.
+.TP
+.BR FIOSETOWN
+The same as the SIOCSPGRP ioctl
+.SH NOTES
+Linux assumes that half of the send/receive buffer is used for internal
+kernel structures; thus the sysctls are twice what can be observed
+on the wire.
+
+Linux will only allow port re-use with the SO_REUSEADDR option
+when this option was set both in the previous program that performed
+a bind() to the port and in the program that wants to re-use the port.
+This differs from some implementations (e.g., FreeBSD)
+where only the later program needs to set the SO_REUSEADDR option.
+Typically this difference is invisible, since, for example, a server
+program is designed to always set this option.
+.SH BUGS
+The 
+.B CONFIG_FILTER 
+socket options 
+.B SO_ATTACH_FILTER 
+and 
+.B SO_DETACH_FILTER 
+are 
+not documented. The suggested interface to use them is via the libpcap
+library.
+.SH VERSIONS
+.B SO_BINDTODEVICE 
+was introduced in Linux 2.0.30. 
+.B SO_PASSCRED 
+is new in Linux 2.2.
+The sysctls are new in Linux 2.2.
+.B SO_RCVTIMEO
+and
+.B SO_SNDTIMEO
+are supported since Linux 2.3.41. Earlier, timeouts were fixed to
+a protocol specific setting, and could not be read or written.
+.\" .SH AUTHORS
+.\" This man page was written by Andi Kleen.
+.SH "SEE ALSO"
+.BR getsockopt (2),
+.BR setsockopt (2),
+.BR socket (2),
+.BR capabilities (7),
+.BR ddp (7),
+.BR ip (7),
+.BR packet (7)
author	Michael Kerrisk <mtk.manpages@gmail.com>	2004-11-03 13:51:07 +0000
committer	Michael Kerrisk <mtk.manpages@gmail.com>	2004-11-03 13:51:07 +0000
commit	fea681dafb1363a154b7fc6d59baa83d2a9ebc5c (patch)
tree	8ea275c0f242af739617d0afc3e1b16c4eff3dc2 /man7/socket.7
download	man-pages-fea681dafb1363a154b7fc6d59baa83d2a9ebc5c.tar.gz