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, 0 insertions, 581 deletions
diff --git a/static/freebsd/man4/ip.4 3.html b/static/freebsd/man4/ip.4 3.html deleted file mode 100644 index 29442b8d..00000000 --- a/static/freebsd/man4/ip.4 3.html +++ /dev/null @@ -1,581 +0,0 @@ -<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> |