s/PF_/AF_/ for socket family conistants. Reasons: the AF_ and

PF_ constants have always had the same values; there never has been a protocol family that had more than one address family, and POSIX.1-2001 only specifies the AF_* constants.
author: Michael Kerrisk <mtk.manpages@gmail.com> 2008-08-08 16:28:06 +0000
committer: Michael Kerrisk <mtk.manpages@gmail.com> 2008-08-08 16:28:06 +0000
commit: 10874173dba2edf045eebd9e85945970182dbaf6 (patch)
tree: ec42e47e1a8fc25ca4e816fd99a570404f3aa5c5 /man7/socket.7
parent: ea6ac50ed39e1c963454c837065ef7beeaccb0b8 (diff)
download: man-pages-10874173dba2edf045eebd9e85945970182dbaf6.tar.gz
1 files changed, 8 insertions, 728 deletions
diff --git a/man7/socket.7 b/man7/socket.7
index 41b37f1b44..a191ad44b7 100644
--- a/man7/socket.7
+++ b/man7/socket.7
@@ -1,728 +1,8 @@
-'\" 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, <mtk.manpages@gmail.com>
-.\"	Added description of SO_ACCEPTCONN
-.\" 2004-05-20, aeb, added SO_RCVTIMEO/SO_SNDTIMEO text.
-.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
-.\"     Added notes on capability requirements
-.\"	A few small grammar fixes
-.\"
-.\" FIXME probably all PF_* should be AF_* in this page, since
-.\"        POSIX only specifies the latter values.
-.\"
-.TH SOCKET 7 2007-12-28 Linux "Linux Programmer's Manual"
-.SH NAME
-socket \- Linux socket interface
-.SH SYNOPSIS
-.B #include <sys/socket.h>
-.sp
-.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.
-.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.
-
-.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 I/O 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).
-.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}
-.\" FIXME . The following is 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
-.BR poll (2)
-and
-.BR select (2)
-is to let the kernel inform the application about events
-via a
-.B SIGIO
-signal.
-For that the
-.B O_ASYNC
-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.
-.SS 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:
-.\" SO_ACCEPTCONN is in POSIX.1-2001, 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 (2).
-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 (2).
-.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_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_BSDCOMPAT
-Enable BSD bug-to-bug compatibility.
-This is used by the UDP protocol module in Linux 2.0 and 2.2.
-If enabled ICMP errors received for a UDP socket will not be passed
-to the user program.
-In later kernel versions, support for this option has been phased out:
-Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning
-(printk()) if a program uses this option.
-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 was removed in Linux 2.2.
-.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_ERROR
-Get and clear the pending socket error.
-Only valid as a
-.BR getsockopt (2).
-Expects an integer.
-.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_KEEPALIVE
-Enable sending of keep-alive messages on connection-oriented sockets.
-Expects an integer boolean flag.
-.TP
-.B SO_LINGER
-Sets or gets the
-.B SO_LINGER
-option.
-The argument is a
-.I linger
-structure.
-.sp
-.in +4n
-.nf
-struct linger {
-    int l_onoff;    /* linger active */
-    int l_linger;   /* how many seconds to linger for */
-};
-.fi
-.in
-.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_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
-.B SO_PASSCRED
-Enable or disable the receiving of the
-.B SCM_CREDENTIALS
-control message.
-For more information see
-.BR unix (7).
-.\" FIXME Document SO_PASSSEC, added in 2.6.18; there is some info
-.\" in the 2.6.18 ChangeLog
-.TP
-.B SO_PEERCRED
-Return the credentials of the foreign process connected to this socket.
-This is only possible for connected
-.B PF_UNIX
-stream sockets and
-.B PF_UNIX
-stream and datagram socket pairs created using
-.BR socketpair (2);
-see
-.BR unix (7).
-The returned credentials are those that were in effect at the time
-of the call to
-.BR connect (2)
-or
-.BR socketpair (2).
-Argument is a
-.I ucred
-structure.
-Only valid as a
-.BR getsockopt (2).
-.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_RCVBUF
-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),
-and this doubled value is returned by
-.BR getsockopt (2).
-The default value is set by the
-.I rmem_default
-sysctl and the maximum allowed value is set by the
-.I rmem_max
-sysctl.
-The minimum (doubled) value for this option is 256.
-.TP
-.BR SO_RCVBUFFORCE " (since Linux 2.6.14)"
-Using this socket option, a privileged
-.RB ( CAP_NET_ADMIN )
-process can perform the same task as
-.BR SO_RCVBUF ,
-but the
-.I rmem_max
-limit can be overridden.
-.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 initialized to 1.
-.B SO_SNDLOWAT
-is not changeable on Linux
-.RB ( setsockopt (2)
-fails with the error
-.BR ENOPROTOOPT ).
-.B SO_RCVLOWAT
-is changeable
-only since Linux 2.4.
-The
-.BR select (2)
-and
-.BR poll (2)
-system calls currently do not respect the
-.B SO_RCVLOWAT
-setting on Linux,
-and mark a socket readable when even a single byte of data is available.
-A subsequent read from the socket will block until
-.B SO_RCVLOWAT
-bytes are available.
-.\" See http://marc.theaimsgroup.com/?l=linux-kernel&m=111049368106984&w=2
-.\" Tested on kernel 2.6.14 -- mtk, 30 Nov 05
-.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 argument is a
-.IR "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
-.B EAGAIN
-or
-.B EWOULDBLOCK
-.\" in fact to EAGAIN
-just as if the socket was specified to be non-blocking.
-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 read (2),
-.BR recvmsg (2),
-.BR send (2),
-.BR sendmsg (2));
-timeouts have no effect for
-.BR select (2),
-.BR poll (2),
-.BR epoll_wait (2),
-etc.
-.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.
-Argument is an integer boolean flag.
-.TP
-.B SO_SNDBUF
-Sets or gets the maximum socket send 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),
-and this doubled value is returned by
-.BR getsockopt (2).
-The default value is set by the
-.I wmem_default
-sysctl and the maximum allowed value is set by the
-.I wmem_max
-sysctl.
-The minimum (doubled) value for this option is 2048.
-.TP
-.BR SO_SNDBUFFORCE " (since Linux 2.6.14)"
-Using this socket option, a privileged
-.RB ( CAP_NET_ADMIN )
-process can perform the same task as
-.BR SO_SNDBUF ,
-but the
-.I wmem_max
-limit can be overridden.
-.TP
-.B SO_TIMESTAMP
-Enable or disable the receiving of the
-.B SO_TIMESTAMP
-control message.
-The timestamp control message is sent with level
-.B SOL_SOCKET
-and the
-.I cmsg_data
-field is a
-.I "struct timeval"
-indicating the
-reception time of the last packet passed to the user in this call.
-See
-.BR cmsg (3)
-for details on control messages.
-.TP
-.B SO_TYPE
-Gets the socket type as an integer (like
-.BR SOCK_STREAM ).
-Can only be read
-with
-.BR getsockopt (2).
-.SS 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
-.BR fcntl (2)
-or
-.B SIOCSPGRP
-.BR ioctl (2),
-.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 real-time signal using the
-.B F_SETSIG
-.BR 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)
-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.
-.\" .SS Ancillary Messages
-.SS Sysctls
-The core socket networking sysctls can be accessed using the
-.I /proc/sys/net/core/*
-files or with the
-.BR sysctl (2)
-interface.
-.TP
-.I rmem_default
-contains the default setting in bytes of the socket receive buffer.
-.TP
-.I 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
-.I wmem_default
-contains the default setting in bytes of the socket send buffer.
-.TP
-.I 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
-.I netdev_max_backlog
-Maximum number of packets in the global input queue.
-.TP
-.I 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
-.SS Ioctls
-These operations can be accessed using
-.BR ioctl (2):
-
-.in +4n
-.nf
-.IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");"
-.fi
-.in
-.TP
-.B SIOCGSTAMP
-Return a
-.I 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
-.IR "struct timeval" .
-.\"
-This ioctl should only be used if the socket option
-.B SO_TIMESTAMP
-is not set on the socket.
-Otherwise, it returns the timestamp of the
-last packet that was received while
-.B SO_TIMESTAMP
-was not set, or it fails if no such packet has been received,
-(i.e.,
-.BR ioctl (2)
-returns \-1 with
-.I errno
-set to
-.BR ENOENT ).
-.TP
-.B 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
-.IR 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 I/O mode of the socket.
-Asynchronous I/O 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.
-(This operation is synonymous with the use of
-.BR fcntl (2)
-to set the
-.B O_ASYNC
-flag.)
-.\"
-.TP
-.B SIOCGPGRP
-Get the current process or process group that receives
-.B SIGIO
-or
-.B SIGURG
-signals,
-or 0
-when none is set.
-.PP
-Valid
-.BR fcntl (2)
-operations:
-.TP
-.B FIOGETOWN
-The same as the
-.B SIOCGPGRP
-.BR ioctl (2).
-.TP
-.B FIOSETOWN
-The same as the
-.B SIOCSPGRP
-.BR ioctl (2).
-.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 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
-.B SO_REUSEADDR
-option
-when this option was set both in the previous program that performed a
-.BR bind (2)
-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
-.B 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 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)
+.TH SOCKET 7 2008-08-07 Linux "Linux Programmer's Manual"
+.TH SOCKET 7 2008-08-07 Linux "Linux Programmer's Manual"
+.TH SOCKET 7 2008-08-07 Linux "Linux Programmer's Manual"
+.TH SOCKET 7 2008-08-07 Linux "Linux Programmer's Manual"
+.TH SOCKET 7 2008-08-07 Linux "Linux Programmer's Manual"
+.TH SOCKET 7 2008-08-07 Linux "Linux Programmer's Manual"
+.TH SOCKET 7 2008-08-07 Linux "Linux Programmer's Manual"
+.TH SOCKET 7 2008-08-07 Linux "Linux Programmer's Manual"
author	Michael Kerrisk <mtk.manpages@gmail.com>	2008-08-08 16:28:06 +0000
committer	Michael Kerrisk <mtk.manpages@gmail.com>	2008-08-08 16:28:06 +0000
commit	10874173dba2edf045eebd9e85945970182dbaf6 (patch)
tree	ec42e47e1a8fc25ca4e816fd99a570404f3aa5c5 /man7/socket.7
parent	ea6ac50ed39e1c963454c837065ef7beeaccb0b8 (diff)
download	man-pages-10874173dba2edf045eebd9e85945970182dbaf6.tar.gz