path: root/static/netbsd/man4/ip.4 3.html

<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/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 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 &#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>/<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 &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">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">&lt;<a class="In">netinet/portalgo.h</a>&gt;</code>. For
    example,</p>
<div class="Bd Pp Li">
<pre>int algo = PORTALGO_ALGO_RANDOM_PICK;       /* see &lt;netinet/portalgo.h&gt; */
setsockopt(s, IPPROTO_IP, IP_PORTALGO, &amp;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 &lt;netinet/in.h&gt; */
setsockopt(s, IPPROTO_IP, IP_PORTRANGE, &amp;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, &amp;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, &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, 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. 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, &amp;idx, sizeof(idx));</pre>
</div>
<p class="Pp">where &quot;ifindex&quot; 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, &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 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, &amp;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, &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>
</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 &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 = 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
    &#x2014; 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>