diff options
Diffstat (limited to 'static/freebsd/man4/ip.4 3.html')
| -rw-r--r-- | static/freebsd/man4/ip.4 3.html | 581 |
1 files changed, 581 insertions, 0 deletions
diff --git a/static/freebsd/man4/ip.4 3.html b/static/freebsd/man4/ip.4 3.html new file mode 100644 index 00000000..29442b8d --- /dev/null +++ b/static/freebsd/man4/ip.4 3.html @@ -0,0 +1,581 @@ +<table class="head"> + <tr> + <td class="head-ltitle">IP(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">IP(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">ip</code> — <span class="Nd">Internet + Protocol</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">sys/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/socket.h</a>></code> + <br/> + <code class="In">#include <<a class="In">netinet/in.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">socket</code>(<var class="Fa" style="white-space: nowrap;">AF_INET</var>, + <var class="Fa" style="white-space: nowrap;">SOCK_RAW</var>, + <var class="Fa" style="white-space: nowrap;">proto</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">IP is the transport layer protocol used by the Internet protocol + family. Options may be set at the IP level when using higher-level protocols + that are based on IP (such as TCP and UDP). It may also be accessed through + a “raw socket” when developing new protocols, or + special-purpose applications.</p> +<p class="Pp">There are several IP-level <a class="Xr">setsockopt(2)</a> and + <a class="Xr">getsockopt(2)</a> options. <code class="Dv">IP_OPTIONS</code> + may be used to provide IP options to be transmitted in the IP header of each + outgoing packet or to examine the header options on incoming packets. IP + options may be used with any socket type in the Internet family. The format + of IP options to be sent is that specified by the IP protocol specification + (RFC-791), with one exception: the list of addresses for Source Route + options must include the first-hop gateway at the beginning of the list of + gateways. The first-hop gateway address will be extracted from the option + list and the size adjusted accordingly before use. To disable previously + specified options, use a zero-length buffer:</p> +<div class="Bd Pp Li"> +<pre>setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);</pre> +</div> +<p class="Pp"><code class="Dv">IP_TOS</code> may be used to set the differential + service codepoint (DSCP) and the explicit congestion notification (ECN) + codepoint. Setting the ECN codepoint - the two least significant bits - on a + socket using a transport protocol implementing ECN has no effect.</p> +<p class="Pp"><code class="Dv">IP_TTL</code> configures the time-to-live (TTL) + field in the IP header for <code class="Dv">SOCK_STREAM</code>, + <code class="Dv">SOCK_DGRAM</code>, and certain types of + <code class="Dv">SOCK_RAW</code> sockets. For example,</p> +<div class="Bd Pp Li"> +<pre>int tos = IPTOS_DSCP_EF; /* see <netinet/ip.h> */ +setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); + +int ttl = 60; /* max = 255 */ +setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl));</pre> +</div> +<p class="Pp"><code class="Dv">IP_IPSEC_POLICY</code> controls IPSec policy for + sockets. For example,</p> +<div class="Bd Pp Li"> +<pre>const char *policy = "in ipsec ah/transport//require"; +char *buf = ipsec_set_policy(policy, strlen(policy)); +setsockopt(s, IPPROTO_IP, IP_IPSEC_POLICY, buf, ipsec_get_policylen(buf));</pre> +</div> +<p class="Pp"><code class="Dv">IP_MINTTL</code> may be used to set the minimum + acceptable TTL a packet must have when received on a socket. All packets + with a lower TTL are silently dropped. This option is only really useful + when set to 255, preventing packets from outside the directly connected + networks reaching local listeners on sockets.</p> +<p class="Pp"><code class="Dv">IP_DONTFRAG</code> may be used to set the Don't + Fragment flag on IP packets. Currently this option is respected only on + <a class="Xr">udp(4)</a> and raw <code class="Nm">ip</code> sockets, unless + the <code class="Dv">IP_HDRINCL</code> option has been set. On + <a class="Xr">tcp(4)</a> sockets, the Don't Fragment flag is controlled by + the Path MTU Discovery option. Sending a packet larger than the MTU size of + the egress interface, determined by the destination address, returns an + <code class="Er">EMSGSIZE</code> error.</p> +<p class="Pp">If the <code class="Dv">IP_ORIGDSTADDR</code> option is enabled on + a <code class="Dv">SOCK_DGRAM</code> socket, the + <a class="Xr">recvmsg(2)</a> call will return the destination IP address and + destination port for a UDP datagram. The <var class="Vt">msg_control</var> + field in the <var class="Vt">msghdr</var> structure points to a buffer that + contains a <var class="Vt">cmsghdr</var> structure followed by the + sockaddr_in structure. The <var class="Vt">cmsghdr</var> fields have the + following values:</p> +<div class="Bd Pp Li"> +<pre>cmsg_len = CMSG_LEN(sizeof(struct sockaddr_in)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_ORIGDSTADDR</pre> +</div> +<p class="Pp">If the <code class="Dv">IP_RECVDSTADDR</code> option is enabled on + a <code class="Dv">SOCK_DGRAM</code> socket, the + <a class="Xr">recvmsg(2)</a> call will return the destination IP address for + a UDP datagram. The <var class="Vt">msg_control</var> field in the + <var class="Vt">msghdr</var> structure points to a buffer that contains a + <var class="Vt">cmsghdr</var> structure followed by the IP address. The + <var class="Vt">cmsghdr</var> fields have the following values:</p> +<div class="Bd Pp Li"> +<pre>cmsg_len = CMSG_LEN(sizeof(struct in_addr)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVDSTADDR</pre> +</div> +<p class="Pp">The source address to be used for outgoing UDP datagrams on a + socket can be specified as ancillary data with a type code of + <code class="Dv">IP_SENDSRCADDR</code>. The msg_control field in the msghdr + structure should point to a buffer that contains a + <var class="Vt">cmsghdr</var> structure followed by the IP address. The + cmsghdr fields should have the following values:</p> +<div class="Bd Pp Li"> +<pre>cmsg_len = CMSG_LEN(sizeof(struct in_addr)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_SENDSRCADDR</pre> +</div> +<p class="Pp">The socket should be either bound to + <code class="Dv">INADDR_ANY</code> and a local port, and the address + supplied with <code class="Dv">IP_SENDSRCADDR</code> shouldn't be + <code class="Dv">INADDR_ANY</code>, or the socket should be bound to a local + address and the address supplied with <code class="Dv">IP_SENDSRCADDR</code> + should be <code class="Dv">INADDR_ANY</code>. In the latter case bound + address is overridden via generic source address selection logic, which + would choose IP address of interface closest to destination.</p> +<p class="Pp">For convenience, <code class="Dv">IP_SENDSRCADDR</code> is defined + to have the same value as <code class="Dv">IP_RECVDSTADDR</code>, so the + <code class="Dv">IP_RECVDSTADDR</code> control message from + <a class="Xr">recvmsg(2)</a> can be used directly as a control message for + <a class="Xr">sendmsg(2)</a>.</p> +<p class="Pp">If the <code class="Dv">IP_ONESBCAST</code> option is enabled on a + <code class="Dv">SOCK_DGRAM</code> or a <code class="Dv">SOCK_RAW</code> + socket, the destination address of outgoing broadcast datagrams on that + socket will be forced to the undirected broadcast address, + <code class="Dv">INADDR_BROADCAST</code>, before transmission. This is in + contrast to the default behavior of the system, which is to transmit + undirected broadcasts via the first network interface with the + <code class="Dv">IFF_BROADCAST</code> flag set.</p> +<p class="Pp">This option allows applications to choose which interface is used + to transmit an undirected broadcast datagram. For example, the following + code would force an undirected broadcast to be transmitted via the interface + configured with the broadcast address 192.168.2.255:</p> +<div class="Bd Pp Li"> +<pre>char msg[512]; +struct sockaddr_in sin; +int onesbcast = 1; /* 0 = disable (default), 1 = enable */ + +setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast)); +sin.sin_addr.s_addr = inet_addr("192.168.2.255"); +sin.sin_port = htons(1234); +sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin));</pre> +</div> +<p class="Pp">It is the application's responsibility to set the + <code class="Dv">IP_TTL</code> option to an appropriate value in order to + prevent broadcast storms. The application must have sufficient credentials + to set the <code class="Dv">SO_BROADCAST</code> socket level option, + otherwise the <code class="Dv">IP_ONESBCAST</code> option has no effect.</p> +<p class="Pp">If the <code class="Dv">IP_BINDANY</code> option is enabled on a + <code class="Dv">SOCK_STREAM</code>, <code class="Dv">SOCK_DGRAM</code> or a + <code class="Dv">SOCK_RAW</code> socket, one can <a class="Xr">bind(2)</a> + to any address, even one not bound to any available network interface in the + system. This functionality (in conjunction with special firewall rules) can + be used for implementing a transparent proxy. The + <code class="Dv">PRIV_NETINET_BINDANY</code> privilege is needed to set this + option.</p> +<p class="Pp">If the <code class="Dv">IP_RECVTTL</code> option is enabled on a + <code class="Dv">SOCK_DGRAM</code> socket, the <a class="Xr">recvmsg(2)</a> + call will return the IP TTL (time to live) field for a UDP datagram. The + msg_control field in the msghdr structure points to a buffer that contains a + cmsghdr structure followed by the TTL. The cmsghdr fields have the following + values:</p> +<div class="Bd Pp Li"> +<pre>cmsg_len = CMSG_LEN(sizeof(u_char)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVTTL</pre> +</div> +<p class="Pp">If the <code class="Dv">IP_RECVTOS</code> option is enabled on a + <code class="Dv">SOCK_DGRAM</code> socket, the <a class="Xr">recvmsg(2)</a> + call will return the IP TOS (type of service) field for a UDP datagram. The + msg_control field in the msghdr structure points to a buffer that contains a + cmsghdr structure followed by the TOS. The cmsghdr fields have the following + values:</p> +<div class="Bd Pp Li"> +<pre>cmsg_len = CMSG_LEN(sizeof(u_char)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVTOS</pre> +</div> +<p class="Pp">If the <code class="Dv">IP_RECVIF</code> option is enabled on a + <code class="Dv">SOCK_DGRAM</code> socket, the <a class="Xr">recvmsg(2)</a> + call returns a <var class="Vt">struct sockaddr_dl</var> corresponding to the + interface on which the packet was received. The + <var class="Va">msg_control</var> field in the <var class="Vt">msghdr</var> + structure points to a buffer that contains a <var class="Vt">cmsghdr</var> + structure followed by the <var class="Vt">struct sockaddr_dl</var>. The + <var class="Vt">cmsghdr</var> fields have the following values:</p> +<div class="Bd Pp Li"> +<pre>cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVIF</pre> +</div> +<p class="Pp"><code class="Dv">IP_PORTRANGE</code> may be used to set the port + range used for selecting a local port number on a socket with an unspecified + (zero) port number. It has the following possible values:</p> +<dl class="Bl-tag"> + <dt id="IP_PORTRANGE_DEFAULT"><a class="permalink" href="#IP_PORTRANGE_DEFAULT"><code class="Dv">IP_PORTRANGE_DEFAULT</code></a></dt> + <dd>use the default range of values, normally + <code class="Dv">IPPORT_HIFIRSTAUTO</code> through + <code class="Dv">IPPORT_HILASTAUTO</code>. This is adjustable through the + sysctl setting: <var class="Va">net.inet.ip.portrange.first</var> and + <var class="Va">net.inet.ip.portrange.last</var>.</dd> + <dt id="IP_PORTRANGE_HIGH"><a class="permalink" href="#IP_PORTRANGE_HIGH"><code class="Dv">IP_PORTRANGE_HIGH</code></a></dt> + <dd>use a high range of values, normally + <code class="Dv">IPPORT_HIFIRSTAUTO</code> and + <code class="Dv">IPPORT_HILASTAUTO</code>. This is adjustable through the + sysctl setting: <var class="Va">net.inet.ip.portrange.hifirst</var> and + <var class="Va">net.inet.ip.portrange.hilast</var>.</dd> + <dt id="IP_PORTRANGE_LOW"><a class="permalink" href="#IP_PORTRANGE_LOW"><code class="Dv">IP_PORTRANGE_LOW</code></a></dt> + <dd>use a low range of ports, which are normally restricted to privileged + processes on <span class="Ux">UNIX</span> systems. The range is normally + from <code class="Dv">IPPORT_RESERVED</code> - 1 down to + <code class="Li">IPPORT_RESERVEDSTART</code> in descending order. This is + adjustable through the sysctl setting: + <var class="Va">net.inet.ip.portrange.lowfirst</var> and + <var class="Va">net.inet.ip.portrange.lowlast</var>.</dd> +</dl> +<p class="Pp">The range of privileged ports which only may be opened by + root-owned processes may be modified by the + <var class="Va">net.inet.ip.portrange.reservedlow</var> and + <var class="Va">net.inet.ip.portrange.reservedhigh</var> sysctl settings. + The values default to the traditional range, 0 through + <code class="Dv">IPPORT_RESERVED</code> - 1 (0 through 1023), respectively. + Note that these settings do not affect and are not accounted for in the use + or calculation of the other <var class="Va">net.inet.ip.portrange</var> + values above. Changing these values departs from + <span class="Ux">UNIX</span> tradition and has security consequences that + the administrator should carefully evaluate before modifying these + settings.</p> +<p class="Pp">Ports are allocated at random within the specified port range in + order to increase the difficulty of random spoofing attacks. In scenarios + such as benchmarking, this behavior may be undesirable. In these cases, + <var class="Va">net.inet.ip.portrange.randomized</var> can be used to toggle + randomization off.</p> +<section class="Ss"> +<h2 class="Ss" id="Multicast_Options"><a class="permalink" href="#Multicast_Options">Multicast + Options</a></h2> +<p class="Pp">IP multicasting is supported only on + <code class="Dv">AF_INET</code> sockets of type + <code class="Dv">SOCK_DGRAM</code> and <code class="Dv">SOCK_RAW</code>, and + only on networks where the interface driver supports multicasting.</p> +<p class="Pp">The <code class="Dv">IP_MULTICAST_TTL</code> option changes the + time-to-live (TTL) for outgoing multicast datagrams in order to control the + scope of the multicasts:</p> +<div class="Bd Pp Li"> +<pre>u_char ttl; /* range: 0 to 255, default = 1 */ +setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));</pre> +</div> +<p class="Pp">Datagrams with a TTL of 1 are not forwarded beyond the local + network. Multicast datagrams with a TTL of 0 will not be transmitted on any + network, but may be delivered locally if the sending host belongs to the + destination group and if multicast loopback has not been disabled on the + sending socket (see below). Multicast datagrams with TTL greater than 1 may + be forwarded to other networks if a multicast router is attached to the + local network.</p> +<p class="Pp">For hosts with multiple interfaces, where an interface has not + been specified for a multicast group membership, each multicast transmission + is sent from the primary network interface. The + <code class="Dv">IP_MULTICAST_IF</code> option overrides the default for + subsequent transmissions from a given socket:</p> +<div class="Bd Pp Li"> +<pre>struct in_addr addr; +setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));</pre> +</div> +<p class="Pp">where "addr" is the local IP address of the desired + interface or <code class="Dv">INADDR_ANY</code> to specify the default + interface.</p> +<p class="Pp">To specify an interface by index, an instance of + <var class="Vt">ip_mreqn</var> may be passed instead. The + <var class="Vt">imr_ifindex</var> member should be set to the index of the + desired interface, or 0 to specify the default interface. The kernel + differentiates between these two structures by their size.</p> +<p class="Pp">The use of <var class="Vt">IP_MULTICAST_IF</var> is + <i class="Em">not recommended</i>, as multicast memberships are scoped to + each individual interface. It is supported for legacy use only by + applications, such as routing daemons, which expect to be able to transmit + link-local IPv4 multicast datagrams (224.0.0.0/24) on multiple interfaces, + without requesting an individual membership for each interface.</p> +<p class="Pp">An interface's local IP address and multicast capability can be + obtained via the <code class="Dv">SIOCGIFCONF</code> and + <code class="Dv">SIOCGIFFLAGS</code> ioctls. Normal applications should not + need to use this option.</p> +<p class="Pp">If a multicast datagram is sent to a group to which the sending + host itself belongs (on the outgoing interface), a copy of the datagram is, + by default, looped back by the IP layer for local delivery. The + <code class="Dv">IP_MULTICAST_LOOP</code> option gives the sender explicit + control over whether or not subsequent datagrams are looped back:</p> +<div class="Bd Pp Li"> +<pre>u_char loop; /* 0 = disable, 1 = enable (default) */ +setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));</pre> +</div> +<p class="Pp">This option improves performance for applications that may have no + more than one instance on a single host (such as a routing daemon), by + eliminating the overhead of receiving their own transmissions. It should + generally not be used by applications for which there may be more than one + instance on a single host (such as a conferencing program) or for which the + sender does not belong to the destination group (such as a time querying + program).</p> +<p class="Pp">The sysctl setting <var class="Va">net.inet.ip.mcast.loop</var> + controls the default setting of the + <code class="Dv">IP_MULTICAST_LOOP</code> socket option for new sockets.</p> +<p class="Pp">A multicast datagram sent with an initial TTL greater than 1 may + be delivered to the sending host on a different interface from that on which + it was sent, if the host belongs to the destination group on that other + interface. The loopback control option has no effect on such delivery.</p> +<p class="Pp">A host must become a member of a multicast group before it can + receive datagrams sent to the group. To join a multicast group, use the + <code class="Dv">IP_ADD_MEMBERSHIP</code> option:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreqn mreqn; +setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreqn, sizeof(mreqn));</pre> +</div> +<p class="Pp">where <var class="Fa">mreqn</var> is the following structure:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreqn { + struct in_addr imr_multiaddr; /* IP multicast address of group */ + struct in_addr imr_address; /* local IP address of interface */ + int imr_ifindex; /* interface index */ +}</pre> +</div> +<p class="Pp"><var class="Va">imr_ifindex</var> should be set to the index of a + particular multicast-capable interface if the host is multihomed. If + <var class="Va">imr_ifindex</var> is non-zero, value of + <var class="Va">imr_interface</var> is ignored. Otherwise, if + <var class="Va">imr_ifindex</var> is 0, kernel will use IP address from + <var class="Va">imr_interface</var> to lookup the interface. Value of + <var class="Va">imr_interface</var> may be set to + <var class="Va">INADDR_ANY</var> to choose the default interface, although + this is not recommended; this is considered to be the first interface + corresponding to the default route. Otherwise, the first multicast-capable + interface configured in the system will be used.</p> +<p class="Pp">Legacy <var class="Vt">struct ip_mreq</var>, that lacks + <var class="Va">imr_ifindex</var> field is also supported by + <code class="Dv">IP_ADD_MEMBERSHIP</code> setsockopt. In this case kernel + would behave as if <var class="Va">imr_ifindex</var> was set to zero: + <var class="Va">imr_interface</var> will be used to lookup interface.</p> +<p class="Pp">Prior to <span class="Ux">FreeBSD 7.0</span>, if the + <var class="Va">imr_interface</var> member is within the network range + <code class="Li">0.0.0.0/8</code>, it is treated as an interface index in + the system interface MIB, as per the RIP Version 2 MIB Extension (RFC-1724). + In versions of <span class="Ux">FreeBSD</span> since 7.0, this behavior is + no longer supported. Developers should instead use the RFC 3678 multicast + source filter APIs; in particular, + <code class="Dv">MCAST_JOIN_GROUP</code>.</p> +<p class="Pp">Up to <code class="Dv">IP_MAX_MEMBERSHIPS</code> memberships may + be added on a single socket. Membership is associated with a single + interface; programs running on multihomed hosts may need to join the same + group on more than one interface.</p> +<p class="Pp">To drop a membership, use:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreq mreq; +setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));</pre> +</div> +<p class="Pp">where <var class="Fa">mreq</var> contains the same values as used + to add the membership. Memberships are dropped when the socket is closed or + the process exits.</p> +<p class="Pp">The IGMP protocol uses the primary IP address of the interface as + its identifier for group membership. This is the first IP address configured + on the interface. If this address is removed or changed, the results are + undefined, as the IGMP membership state will then be inconsistent. If + multiple IP aliases are configured on the same interface, they will be + ignored.</p> +<p class="Pp">This shortcoming was addressed in IPv6; MLDv2 requires that the + unique link-local address for an interface is used to identify an MLDv2 + listener.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Source-Specific_Multicast_Options"><a class="permalink" href="#Source-Specific_Multicast_Options">Source-Specific + Multicast Options</a></h2> +<p class="Pp">Since <span class="Ux">FreeBSD 8.0</span>, the use of + Source-Specific Multicast (SSM) is supported. These extensions require an + IGMPv3 multicast router in order to make best use of them. If a legacy + multicast router is present on the link, <span class="Ux">FreeBSD</span> + will simply downgrade to the version of IGMP spoken by the router, and the + benefits of source filtering on the upstream link will not be present, + although the kernel will continue to squelch transmissions from blocked + sources.</p> +<p class="Pp">Each group membership on a socket now has a filter mode:</p> +<dl class="Bl-tag"> + <dt id="MCAST_EXCLUDE"><a class="permalink" href="#MCAST_EXCLUDE"><code class="Dv">MCAST_EXCLUDE</code></a></dt> + <dd>Datagrams sent to this group are accepted, unless the source is in a list + of blocked source addresses.</dd> + <dt id="MCAST_INCLUDE"><a class="permalink" href="#MCAST_INCLUDE"><code class="Dv">MCAST_INCLUDE</code></a></dt> + <dd>Datagrams sent to this group are accepted only if the source is in a list + of accepted source addresses.</dd> +</dl> +<p class="Pp" id="delta-based">Groups joined using the legacy + <code class="Dv">IP_ADD_MEMBERSHIP</code> option are placed in + exclusive-mode, and are able to request that certain sources are blocked or + allowed. This is known as the + <a class="permalink" href="#delta-based"><i class="Em">delta-based + API</i></a>.</p> +<p class="Pp">To block a multicast source on an existing group membership:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreq_source mreqs; +setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs));</pre> +</div> +<p class="Pp">where <var class="Fa">mreqs</var> is the following structure:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreq_source { + struct in_addr imr_multiaddr; /* IP multicast address of group */ + struct in_addr imr_sourceaddr; /* IP address of source */ + struct in_addr imr_interface; /* local IP address of interface */ +}</pre> +</div> +<var class="Va">imr_sourceaddr</var> should be set to the address of the source + to be blocked. +<p class="Pp">To unblock a multicast source on an existing group:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreq_source mreqs; +setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs));</pre> +</div> +<p class="Pp">The <code class="Dv">IP_BLOCK_SOURCE</code> and + <code class="Dv">IP_UNBLOCK_SOURCE</code> options are <i class="Em">not + permitted</i> for inclusive-mode group memberships.</p> +<p class="Pp">To join a multicast group in <code class="Dv">MCAST_INCLUDE</code> + mode with a single source, or add another source to an existing + inclusive-mode membership:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreq_source mreqs; +setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));</pre> +</div> +<p class="Pp">To leave a single source from an existing group in inclusive + mode:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreq_source mreqs; +setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs));</pre> +</div> +If this is the last accepted source for the group, the membership will be + dropped. +<p class="Pp" id="full-state">The + <code class="Dv">IP_ADD_SOURCE_MEMBERSHIP</code> and + <code class="Dv">IP_DROP_SOURCE_MEMBERSHIP</code> options are + <i class="Em">not accepted</i> for exclusive-mode group memberships. + However, both exclusive and inclusive mode memberships support the use of + the <a class="permalink" href="#full-state"><i class="Em">full-state + API</i></a> documented in RFC 3678. For management of source filter lists + using this API, please refer to <a class="Xr">sourcefilter(3)</a>.</p> +<p class="Pp">The sysctl settings + <var class="Va">net.inet.ip.mcast.maxsocksrc</var> and + <var class="Va">net.inet.ip.mcast.maxgrpsrc</var> are used to specify an + upper limit on the number of per-socket and per-group source filter entries + which the kernel may allocate.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Raw_IP_Sockets"><a class="permalink" href="#Raw_IP_Sockets">Raw + IP Sockets</a></h2> +<p class="Pp">Raw IP sockets are connectionless, and are normally used with the + <a class="Xr">sendto(2)</a> and <a class="Xr">recvfrom(2)</a> calls, though + the <a class="Xr">connect(2)</a> call may also be used to fix the + destination for future packets (in which case the <a class="Xr">read(2)</a> + or <a class="Xr">recv(2)</a> and <a class="Xr">write(2)</a> or + <a class="Xr">send(2)</a> system calls may be used).</p> +<p class="Pp">If <var class="Fa">proto</var> is 0, the default protocol + <code class="Dv">IPPROTO_RAW</code> is used for outgoing packets, and only + incoming packets destined for that protocol are received. If + <var class="Fa">proto</var> is non-zero, that protocol number will be used + on outgoing packets and to filter incoming packets.</p> +<p class="Pp">Outgoing packets automatically have an IP header prepended to them + (based on the destination address and the protocol number the socket is + created with), unless the <code class="Dv">IP_HDRINCL</code> option has been + set. Unlike in previous <span class="Ux">BSD</span> releases, incoming + packets are received with IP header and options intact, leaving all fields + in network byte order.</p> +<p class="Pp"><code class="Dv">IP_HDRINCL</code> indicates the complete IP + header is included with the data and may be used only with the + <code class="Dv">SOCK_RAW</code> type.</p> +<div class="Bd Pp Li"> +<pre>#include <netinet/in_systm.h> +#include <netinet/ip.h> + +int hincl = 1; /* 1 = on, 0 = off */ +setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl));</pre> +</div> +<p class="Pp">Unlike previous <span class="Ux">BSD</span> releases, the program + must set all the fields of the IP header, including the following:</p> +<div class="Bd Pp Li"> +<pre>ip->ip_v = IPVERSION; +ip->ip_hl = hlen >> 2; +ip->ip_id = 0; /* 0 means kernel set appropriate value */ +ip->ip_off = htons(offset); +ip->ip_len = htons(len);</pre> +</div> +<p class="Pp">The packet should be provided as is to be sent over wire. This + implies all fields, including <var class="Va">ip_len</var> and + <var class="Va">ip_off</var> to be in network byte order. See + <a class="Xr">byteorder(3)</a> for more information on network byte order. + If the <var class="Va">ip_id</var> field is set to 0 then the kernel will + choose an appropriate value. If the header source address is set to + <code class="Dv">INADDR_ANY</code>, the kernel will choose an appropriate + address.</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1> +<p class="Pp">A socket operation may fail with one of the following errors + returned:</p> +<dl class="Bl-tag"> + <dt id="EISCONN">[<a class="permalink" href="#EISCONN"><code class="Er">EISCONN</code></a>]</dt> + <dd>when trying to establish a connection on a socket which already has one, + or when trying to send a datagram with the destination address specified + and the socket is already connected;</dd> + <dt id="ENOTCONN">[<a class="permalink" href="#ENOTCONN"><code class="Er">ENOTCONN</code></a>]</dt> + <dd>when trying to send a datagram, but no destination address is specified, + and the socket has not been connected;</dd> + <dt id="ENOBUFS">[<a class="permalink" href="#ENOBUFS"><code class="Er">ENOBUFS</code></a>]</dt> + <dd>when the system runs out of memory for an internal data structure;</dd> + <dt id="EADDRNOTAVAIL">[<a class="permalink" href="#EADDRNOTAVAIL"><code class="Er">EADDRNOTAVAIL</code></a>]</dt> + <dd>when an attempt is made to create a socket with a network address for + which no network interface exists.</dd> + <dt id="EACCES">[<a class="permalink" href="#EACCES"><code class="Er">EACCES</code></a>]</dt> + <dd>when an attempt is made to create a raw IP socket by a non-privileged + process.</dd> +</dl> +<p class="Pp">The following errors specific to IP may occur when setting or + getting IP options:</p> +<dl class="Bl-tag"> + <dt id="EINVAL">[<a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a>]</dt> + <dd>An unknown socket option name was given.</dd> + <dt id="EINVAL~2">[<a class="permalink" href="#EINVAL~2"><code class="Er">EINVAL</code></a>]</dt> + <dd>The IP option field was improperly formed; an option field was shorter + than the minimum value or longer than the option buffer provided.</dd> +</dl> +<p class="Pp">The following errors may occur when attempting to send IP + datagrams via a “raw socket” with the + <code class="Dv">IP_HDRINCL</code> option set:</p> +<dl class="Bl-tag"> + <dt id="EINVAL~3">[<a class="permalink" href="#EINVAL~3"><code class="Er">EINVAL</code></a>]</dt> + <dd>The user-supplied <var class="Va">ip_len</var> field was not equal to the + length of the datagram written to the socket.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">getsockopt(2)</a>, <a class="Xr">recv(2)</a>, + <a class="Xr">send(2)</a>, <a class="Xr">byteorder(3)</a>, + <a class="Xr">CMSG_DATA(3)</a>, <a class="Xr">sourcefilter(3)</a>, + <a class="Xr">icmp(4)</a>, <a class="Xr">igmp(4)</a>, + <a class="Xr">inet(4)</a>, <a class="Xr">intro(4)</a>, + <a class="Xr">multicast(4)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">D. Thaler</span>, + <span class="RsA">B. Fenner</span>, and <span class="RsA">B. Quinn</span>, + <span class="RsT">Socket Interface Extensions for Multicast Source + Filters</span>, <span class="RsN">RFC 3678</span>, <span class="RsD">Jan + 2004</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">ip</code> protocol appeared in + <span class="Ux">4.2BSD</span>. The <var class="Vt">ip_mreqn</var> structure + appeared in Linux 2.4.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Before <span class="Ux">FreeBSD 10.0</span> packets received on + raw IP sockets had the <var class="Va">ip_hl</var> subtracted from the + <var class="Va">ip_len</var> field.</p> +<p class="Pp">Before <span class="Ux">FreeBSD 11.0</span> packets received on + raw IP sockets had the <var class="Va">ip_len</var> and + <var class="Va">ip_off</var> fields converted to host byte order. Packets + written to raw IP sockets were expected to have <var class="Va">ip_len</var> + and <var class="Va">ip_off</var> in host byte order.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 9, 2021</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |