diff options
| author | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 19:55:15 -0400 |
|---|---|---|
| committer | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 19:55:15 -0400 |
| commit | 253e67c8b3a72b3a4757fdbc5845297628db0a4a (patch) | |
| tree | adf53b66087aa30dfbf8bf391a1dadb044c3bf4d /static/netbsd/man4/ip.4 3.html | |
| parent | a9157ce950dfe2fc30795d43b9d79b9d1bffc48b (diff) | |
docs: Added All NetBSD Manuals
Diffstat (limited to 'static/netbsd/man4/ip.4 3.html')
| -rw-r--r-- | static/netbsd/man4/ip.4 3.html | 379 |
1 files changed, 379 insertions, 0 deletions
diff --git a/static/netbsd/man4/ip.4 3.html b/static/netbsd/man4/ip.4 3.html new file mode 100644 index 00000000..bf3581ba --- /dev/null +++ b/static/netbsd/man4/ip.4 3.html @@ -0,0 +1,379 @@ +<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/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 network 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>/<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> and <code class="Dv">IP_TTL</code> + may be used to set the type-of-service and time-to-live fields in the IP + header for <code class="Dv">SOCK_STREAM</code> and + <code class="Dv">SOCK_DGRAM</code> sockets. For example,</p> +<div class="Bd Pp Li"> +<pre>int tos = IPTOS_LOWDELAY; /* 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">The <code class="Dv">IP_RECVPKTINFO</code> option can be used to + turn on receiving of information about the destination address of the + packet, and the interface index. The information is passed in a + <var class="Vt">struct in_pktinfo</var> structure, which contains</p> +<div class="Bd Pp Li"> +<pre> struct in_addr ipi_addr; /* the source or destination address */ + unsigned int ipi_ifindex; /* the interface index */</pre> +</div> +<p class="Pp">and added to the control portion of the message: The cmsghdr + fields have the following values:</p> +<div class="Bd Pp Li"> +<pre>cmsg_len = CMSG_LEN(sizeof(struct in_pktinfo)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_PKTINFO</pre> +</div> +<p class="Pp">For <a class="Xr">sendmsg(2)</a>, the source address or output + interface can be specified by adding an <code class="Dv">IP_PKTINFO</code> + message to the control part of the message on a + <code class="Dv">SOCK_DGRAM</code> or <code class="Dv">SOCK_RAW</code> + socket. Setting ipi_ifindex will cause the primary address of that interface + to be used; setting ipi_addr will directly choose that address. The + <code class="Dv">IP_PKTINFO</code> cmsghdr structure from a received message + may be used unchanged, in which case the outgoing message will be sent from + the address the incoming message was received on.</p> +<p class="Pp">Setting the <code class="Dv">IP_PKTINFO</code> option on a socket, + with the same <var class="Vt">struct in_pktinfo</var> structure, will set + the default source address to be used until set again, unless explicitly + overridden on a per-packet basis, as above.</p> +<p class="Pp">The <code class="Dv">IP_PORTALGO</code> can be used to randomize + the port selection. Valid algorithms are described in + <a class="Xr">rfc6056(7)</a> and their respective constants are in + <code class="In"><<a class="In">netinet/portalgo.h</a>></code>. For + example,</p> +<div class="Bd Pp Li"> +<pre>int algo = PORTALGO_ALGO_RANDOM_PICK; /* see <netinet/portalgo.h> */ +setsockopt(s, IPPROTO_IP, IP_PORTALGO, &algo, sizeof(algo));</pre> +</div> +<p class="Pp">The port selection can be also viewed and controlled at a global + level for all IP sockets using the following <a class="Xr">sysctl(7)</a> + variables: <code class="Dv">net.inet.ip.anonportalgo.available</code> and + <code class="Dv">net.inet.ip.anonportalgo.selected</code>.</p> +<p class="Pp"><code class="Dv">IP_PORTRANGE</code> controls how ephemeral ports + are allocated for <code class="Dv">SOCK_STREAM</code> and + <code class="Dv">SOCK_DGRAM</code> sockets. For example,</p> +<div class="Bd Pp Li"> +<pre>int range = IP_PORTRANGE_LOW; /* see <netinet/in.h> */ +setsockopt(s, IPPROTO_IP, IP_PORTRANGE, &range, sizeof(range));</pre> +</div> +<p class="Pp">If the <code class="Dv">IP_RECVDSTADDR</code> option is enabled on + a <code class="Dv">SOCK_DGRAM</code> or <code class="Dv">SOCK_RAW</code> + socket, the <a class="Xr">recvmsg(2)</a> call will return the destination IP + address for a UDP datagram. The msg_control field in the msghdr structure + points to a buffer that contains a cmsghdr structure followed by the IP + address. The cmsghdr 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">For <a class="Xr">sendmsg(2)</a>, the source address can be + specified by adding <code class="Dv">IP_SENDSRCADDR</code> to the control + part of the message on a <code class="Dv">SOCK_DGRAM</code> or + <code class="Dv">SOCK_RAW</code> socket. The + <code class="Dv">IP_RECVDSTADDR</code> cmsghdr structure from a received + message may be used unchanged, in which case the outgoing message will be + sent from the address the incoming message was received on.</p> +<p class="Pp">If the <code class="Dv">IP_RECVIF</code> option is enabled on a + <code class="Dv">SOCK_DGRAM</code> or <code class="Dv">SOCK_RAW</code> + socket, the <a class="Xr">recvmsg(2)</a> call will return a struct + sockaddr_dl corresponding to the interface on which the packet was received. + the msg_control field in the msghdr structure points to a buffer that + contains a cmsghdr structure followed by the struct sockaddr_dl. The cmsghdr + 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">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">KAUTH_REQ_NETWORK_BIND_ANYADDR</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 TTL of the received datagram. The msg_control field in + the msghdr structure points to a buffer that contains a cmsghdr structure + followed by the TTL value. The cmsghdr fields have the following values:</p> +<div class="Bd Pp Li"> +<pre>cmsg_len = CMSG_LEN(sizeof(uint8_t)) +cmsg_level = IPPROTO_IP +cmsg_type = IP_RECVTTL</pre> +</div> +<p class="Pp" id="Generalized">The <code class="Dv">IP_MINTTL</code> option may + be used on <code class="Dv">SOCK_DGRAM</code> or + <code class="Dv">SOCK_STREAM</code> sockets to discard packets with a TTL + lower than the option value. This can be used to implement the + <a class="permalink" href="#Generalized"><i class="Em">Generalized TTL + Security Mechanism (GTSM)</i></a> according to RFC 3682. To discard all + packets with a TTL lower than 255:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>int minttl = 255; +setsockopt(s, IPPROTO_IP, IP_MINTTL, &minttl, sizeof(minttl));</pre> +</div> +<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, 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. 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. An application may also specify + an alternative to the default network interface by index:</p> +<div class="Bd Pp Li"> +<pre>struct uint32_t idx = htonl(ifindex); +setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &idx, sizeof(idx));</pre> +</div> +<p class="Pp">where "ifindex" is an interface index as returned by + <a class="Xr">if_nametoindex(3)</a>.</p> +<p class="Pp">Normal applications should not need to use + <code class="Dv">IP_MULTICAST_IF</code>.</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 router demon), 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">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_mreq mreq; +setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));</pre> +</div> +<p class="Pp">where <var class="Fa">mreq</var> is the following structure:</p> +<div class="Bd Pp Li"> +<pre>struct ip_mreq { + struct in_addr imr_multiaddr; /* multicast group to join */ + struct in_addr imr_interface; /* interface to join on */ +}</pre> +</div> +<p class="Pp"><code class="Dv">imr_interface</code> should be + <code class="Dv">INADDR_ANY</code> to choose the default multicast + interface, or the IP address of a particular multicast-capable interface if + the host is multihomed. Membership is associated with a single interface; + programs running on multihomed hosts may need to join the same group on more + than one interface. Up to <code class="Dv">IP_MAX_MEMBERSHIPS</code> + (currently 20) memberships may be added on a single socket.</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> +</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. Incoming packets are received with IP header and options intact.</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/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 = offset;</pre> +</div> +<p class="Pp">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="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">A socket operation may fail with one of the following errors + returned:</p> +<dl class="Bl-tag"> + <dt>[<code class="Er">EACCES</code>]</dt> + <dd>when an attempt is made to create a raw IP socket by a non-privileged + process.</dd> + <dt>[<code class="Er">EADDRNOTAVAIL</code>]</dt> + <dd>when an attempt is made to create a socket with a network address for + which no network interface exists.</dd> + <dt>[<code class="Er">EISCONN</code>]</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>[<code class="Er">ENOBUFS</code>]</dt> + <dd>when the system runs out of memory for an internal data structure;</dd> + <dt>[<code class="Er">ENOTCONN</code>]</dt> + <dd>when trying to send a datagram, but no destination address is specified, + and the socket hasn't been connected;</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>[<code class="Er">EINVAL</code>]</dt> + <dd>An unknown socket option name was given; or 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> +</section> +<section class="Sh"> +<h1 class="Sh" id="COMPATIBILITY"><a class="permalink" href="#COMPATIBILITY">COMPATIBILITY</a></h1> +<p class="Pp">The <code class="Dv">IP_RECVPKTINFO</code> option is used because + it is directly compatible with Solaris, AIX, etc., and the + <code class="Dv">IP_PKTINFO</code> option is intended to be used in their + manner, to set the default source address for outgoing packets on a + <code class="Dv">SOCK_DGRAM</code> or <code class="Dv">SOCK_RAW</code> + socket. For compatibility with Linux, however, if you attempt to set the + <code class="Dv">IP_PKTINFO</code> option, using an integer parameter as a + boolean value, this will transparently manipulate the + <code class="Dv">IP_RECVPKTINFO</code> option instead. Source code + compatibility with both environments is thus maintained.</p> +</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">CMSG_DATA(3)</a>, + <a class="Xr">ipsec_set_policy(3)</a>, <a class="Xr">icmp(4)</a>, + <a class="Xr">inet(4)</a>, <a class="Xr">intro(4)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsT">Internet Protocol</span>, + <span class="RsR">RFC</span>, <span class="RsN">791</span>, + <span class="RsD">September 1981</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsT">Host Extensions for IP + Multicasting</span>, <span class="RsR">RFC</span>, + <span class="RsN">1112</span>, <span class="RsD">August + 1989</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsT">Requirements for Internet Hosts + — Communication Layers</span>, <span class="RsR">RFC</span>, + <span class="RsN">1122</span>, <span class="RsD">October + 1989</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>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 8, 2020</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> |