docs: Added All FreeBSD Manuals

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> &#x2014; <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
+    &lt;<a class="In">sys/types.h</a>&gt;</code>
+  <br/>
+  <code class="In">#include &lt;<a class="In">sys/socket.h</a>&gt;</code>
+  <br/>
+  <code class="In">#include &lt;<a class="In">netinet/in.h</a>&gt;</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 &#x201C;raw socket&#x201D; 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 &lt;netinet/ip.h&gt; */
+setsockopt(s, IPPROTO_IP, IP_TOS, &amp;tos, sizeof(tos));
+
+int ttl = 60;                   /* max = 255 */
+setsockopt(s, IPPROTO_IP, IP_TTL, &amp;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 = &quot;in ipsec ah/transport//require&quot;;
+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, &amp;onesbcast, sizeof(onesbcast));
+sin.sin_addr.s_addr = inet_addr(&quot;192.168.2.255&quot;);
+sin.sin_port = htons(1234);
+sendto(s, msg, sizeof(msg), 0, &amp;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, &amp;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, &amp;addr, sizeof(addr));</pre>
+</div>
+<p class="Pp">where &quot;addr&quot; 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, &amp;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, &amp;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, &amp;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, &amp;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, &amp;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, &amp;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, &amp;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 &lt;netinet/in_systm.h&gt;
+#include &lt;netinet/ip.h&gt;
+
+int hincl = 1;                  /* 1 = on, 0 = off */
+setsockopt(s, IPPROTO_IP, IP_HDRINCL, &amp;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-&gt;ip_v = IPVERSION;
+ip-&gt;ip_hl = hlen &gt;&gt; 2;
+ip-&gt;ip_id = 0;  /* 0 means kernel set appropriate value */
+ip-&gt;ip_off = htons(offset);
+ip-&gt;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 &#x201C;raw socket&#x201D; 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>