From 3dbef8d0efccec3b4672fea4956339a33ace18d4 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 20 Jul 2005 07:43:05 +0000 Subject: [PATCH] Clarify that port number is 16 bit; reformat long lines --- Changes | 6 ++++++ man7/ip.7 | 60 ++++++++++++++++++++++++++++++++++--------------------- 2 files changed, 43 insertions(+), 23 deletions(-) diff --git a/Changes b/Changes index 55b2150ac..d0004f3b0 100644 --- a/Changes +++ b/Changes @@ -8,6 +8,7 @@ Contributors The following people contributed notes, ideas, or patches that have been incorporated in changes in this release: +Andrew Pimlott ###Andries Brouwer Mike Frysinger @@ -26,3 +27,8 @@ Changes to individual pages stat.2 Mike Frysinger Improve st_blocks description. + +ip.7 + mtk / Andrew Pimlott + Add a couple of words to make it clear that port is a 16-bit number. + Reformat long source lines (no text changed). diff --git a/man7/ip.7 b/man7/ip.7 index d61929ab1..458885197 100644 --- a/man7/ip.7 +++ b/man7/ip.7 @@ -28,8 +28,8 @@ Linux implements the Internet Protocol, version 4, described in RFC\ 791 and RFC\ 1122. .B ip contains a level 2 -multicasting implementation conforming to RFC\ 1112. It also contains an IP -router including a packet filter. +multicasting implementation conforming to RFC\ 1112. +It also contains an IP router including a packet filter. .\" XXX: has someone verified that 2.1 is really 1812 compliant? .PP The programmer's interface is BSD sockets compatible. @@ -90,7 +90,8 @@ are called on an unbound socket, it is automatically bound to a random free port with the local address set to .BR INADDR_ANY . -A TCP local socket address that has been bound is unavailable for some time after closing, +A TCP local socket address that has been bound is unavailable for +some time after closing, unless the .B SO_REUSEADDR flag has been set. Care should be taken when using this flag as it @@ -98,7 +99,8 @@ makes TCP less reliable. .SH "ADDRESS FORMAT" An IP socket address is defined as a combination of an IP interface address -and a port number. The basic IP protocol does not supply port numbers, they +and a 16-bit port number. +The basic IP protocol does not supply port numbers, they are implemented by higher level protocols like .BR udp (7) and @@ -132,7 +134,8 @@ This is required; in Linux 2.2 most networking functions return .B EINVAL when this setting is missing. .I sin_port -contains the port in network byte order. The port numbers below 1024 are called +contains the port in network byte order. +The port numbers below 1024 are called .IR "reserved ports" . Only processes with effective user ID 0 or the .B CAP_NET_BIND_SERVICE @@ -159,7 +162,8 @@ should be only accessed using the library functions or directly with the name resolver (see .BR gethostbyname (3)). IPv4 addresses are divided into unicast, broadcast -and multicast addresses. Unicast addresses specify a single interface of a host, +and multicast addresses. +Unicast addresses specify a single interface of a host, broadcast addresses specify all hosts on a network and multicast addresses address all hosts in a multicast group. Datagrams to broadcast addresses can be only sent or received when the @@ -201,7 +205,8 @@ A boolean integer flag is zero when it is false, otherwise true. .TP .B IP_OPTIONS Sets or get the IP options to be sent with every packet from this -socket. The arguments are a pointer to a memory buffer containing the options +socket. +The arguments are a pointer to a memory buffer containing the options and the option length. The .BR setsockopt (2) @@ -295,7 +300,8 @@ sockets. .B IP_RECVOPTS Pass all incoming IP options to the user in a .I IP_OPTIONS -control message. The routing header and other options are already filled in +control message. +The routing header and other options are already filled in for the local host. Not supported for .I SOCK_STREAM sockets. @@ -309,8 +315,9 @@ options not filled in for this hop. .TP .B IP_TOS -Set or receive the Type-Of-Service (TOS) field that is sent with every IP packet -originating from this socket. It is used to prioritize packets on the network. +Set or receive the Type-Of-Service (TOS) field that is sent +with every IP packet originating from this socket. +It is used to prioritize packets on the network. TOS is a byte. There are some standard TOS flags defined: .B IPTOS_LOWDELAY to minimize delays for interactive traffic, @@ -551,8 +558,8 @@ option. .TP .B IP_MTU Retrieve the current known path MTU of the current socket. -Only valid when the socket has been connected. Returns an integer. Only valid -as a +Only valid when the socket has been connected. Returns an integer. +Only valid as a .BR getsockopt (2). .\" .TP @@ -560,9 +567,12 @@ as a Pass all to-be forwarded packets with the IP Router Alert option -set to this socket. Only valid for raw sockets. This is useful, for instance, for user -space RSVP daemons. The tapped packets are not forwarded by the kernel, it is -the users responsibility to send them out again. Socket binding is ignored, +set to this socket. Only valid for raw sockets. +This is useful, for instance, for user +space RSVP daemons. +The tapped packets are not forwarded by the kernel, it is +the users responsibility to send them out again. +Socket binding is ignored, such packets are only filtered by protocol. Expects an integer flag. .\" @@ -577,8 +587,8 @@ integer. .\" .TP .B IP_MULTICAST_LOOP -Sets or reads a boolean integer argument whether sent multicast packets should be -looped back to the local sockets. +Sets or reads a boolean integer argument whether sent multicast +packets should be looped back to the local sockets. .\" .TP .B IP_ADD_MEMBERSHIP @@ -598,10 +608,12 @@ struct ip_mreqn { .RE .IP .I imr_multiaddr -contains the address of the multicast group the application wants to join or leave. +contains the address of the multicast group the application +wants to join or leave. It must be a valid multicast address. .I imr_address -is the address of the local interface with which the system should join the multicast +is the address of the local interface with which the system +should join the multicast group; if it is equal to .B INADDR_ANY an appropriate interface is chosen by the system. @@ -696,13 +708,14 @@ option. .TP .BR ip_dynaddr " (Boolean; default: disabled)" Enable dynamic socket address and masquerading entry rewriting on interface -address change. This is useful for dialup interface with changing IP addresses. +address change. +This is useful for dialup interface with changing IP addresses. 0 means no rewriting, 1 turns it on and 2 enables verbose mode. .\" .TP .BR ip_forward " (Boolean; default: disabled)" -Enable IP forwarding with a boolean flag. IP forwarding can be also set on a -per interface basis. +Enable IP forwarding with a boolean flag. +IP forwarding can be also set on a per interface basis. .\" .TP .BR ip_local_port_range @@ -790,7 +803,8 @@ received datagrams. Linux has the more general for the same task. .PP .SH ERRORS -.\" XXX document all errors. We should really fix the kernels to give more uniform +.\" XXX document all errors. +.\" We should really fix the kernels to give more uniform .\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.) .TP .B ENOTCONN