ip(4)

NAME

ip - Internet Protocol

SYNOPSIS

#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
int
socket(AF_INET, SOCK_RAW, proto);

DESCRIPTION

IP is the transport layer protocol used by the Internet pro

tocol 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 ac

cessed through a
``raw socket'' when developing new protocols, or special

purpose applications.

There are several IP-level setsockopt(2) and getsockopt(2)

options.
IP_OPTIONS may be used to provide IP options to be transmit

ted in the IP
header of each outgoing packet or to examine the header op

tions 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 speci

fied 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 gate

way 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:

setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);

IP_TOS and IP_TTL may be used to set the type-of-service and

time-to-live
fields in the IP header for SOCK_STREAM, SOCK_DGRAM, and

certain types of
SOCK_RAW sockets. For example,

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));

IP_MINTTL 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.

IP_DONTFRAG may be used to set the Don't Fragment flag on IP

packets.
Currently this option is respected only on udp(4) and Raw

ip(4) sockets,
unless the IP_HDRINCL option has been set. On tcp(4) sock

ets the Don't
Fragment flag is controlled by the Path MTU Discovery op

tion. Sending a
packet larger than the MTU size of the egress interface, de

termined by
the destination address, returns an EMSGSIZE error.

If the IP_RECVDSTADDR option is enabled on a SOCK_DGRAM

socket, the
recvmsg(2) 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 ad

dress. The
cmsghdr fields have the following values:

cmsg_len = sizeof(struct in_addr)
cmsg_level = IPPROTO_IP
cmsg_type = IP_RECVDSTADDR

The source address to be used for outgoing UDP datagrams on

a socket that
is not bound to a specific IP address can be specified as

ancillary data
with a type code of IP_SENDSRCADDR. The msg_control field

in the msghdr
structure should point to a buffer that contains a cmsghdr

structure followed by the IP address. The cmsghdr fields should have the

following
values:

cmsg_len = sizeof(struct in_addr)
cmsg_level = IPPROTO_IP
cmsg_type = IP_SENDSRCADDR

For convenience, IP_SENDSRCADDR is defined to have the same

value as
IP_RECVDSTADDR, so the IP_RECVDSTADDR control message from

recvmsg(2) can
be used directly as a control message for sendmsg(2).

If the IP_ONESBCAST option is enabled on a SOCK_DGRAM or a

SOCK_RAW
socket, the destination address of outgoing broadcast data

grams on that
socket will be forced to the undirected broadcast address,
INADDR_BROADCAST, before transmission. This is in contrast

to the
default behavior of the system, which is to transmit undi

rected broadcasts via the first network interface with the IFF_BROADCAST

flag set.

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:

char msg[512];
struct sockaddr_in sin;
u_char onesbcast = 1; /* 0 = disable (default), 1 = enable

*/

setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, size

of(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));

It is the application's responsibility to set the IP_TTL op

tion to an
appropriate value in order to prevent broadcast storms. The

application
must have sufficient credentials to set the SO_BROADCAST

socket level
option, otherwise the IP_ONESBCAST option has no effect.

If the IP_RECVTTL option is enabled on a SOCK_DGRAM socket,

the
recvmsg(2) 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:

cmsg_len = sizeof(u_char)
cmsg_level = IPPROTO_IP
cmsg_type = IP_RECVTTL

If the IP_RECVIF option is enabled on a SOCK_DGRAM socket,

the recvmsg(2)
call returns a struct sockaddr_dl corresponding to the in

terface on which
the packet was received. The msg_control field in the

msghdr structure
points to a buffer that contains a cmsghdr structure fol

lowed by the
struct sockaddr_dl. The cmsghdr fields have the following

values:

cmsg_len = sizeof(struct sockaddr_dl)
cmsg_level = IPPROTO_IP
cmsg_type = IP_RECVIF

IP_PORTRANGE may be used to set the port range used for se

lecting a local
port number on a socket with an unspecified (zero) port num

ber. It has
the following possible values:

IP_PORTRANGE_DEFAULT use the default range of values, nor

mally

IPPORT_HIFIRSTAUTO through IPPORT_HI

LASTAUTO. This
is adjustable through the sysctl set

ting:
net.inet.ip.portrange.first and net.inet.ip.portrange.last.

IP_PORTRANGE_HIGH use a high range of values, normally

IPPORT_HIFIRSTAUTO and IPPORT_HILAS

TAUTO. This is
adjustable through the sysctl setting:
net.inet.ip.portrange.hifirst and net.inet.ip.portrange.hilast.

IP_PORTRANGE_LOW use a low range of ports, which are

normally

restricted to privileged processes on

UNIX systems.
The range is normally from IPPORT_RE

SERVED - 1 down
to IPPORT_RESERVEDSTART in descending

order. This
is adjustable through the sysctl set

ting:
net.inet.ip.portrange.lowfirst and net.inet.ip.portrange.lowlast.

The range of privileged ports which only may be opened by

root-owned processes may be modified by the

net.inet.ip.portrange.reservedlow and net.inet.ip.portrange.reservedhigh sysctl settings. The

values default
to the traditional range, 0 through IPPORT_RESERVED - 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
net.inet.ip.portrange values above. Changing these values

departs from
UNIX tradition and has security consequences that the admin

istrator
should carefully evaluate before modifying these settings.

Ports are allocated at random within the specified port

range in order to
increase the difficulty of random spoofing attacks. In sce

narios such as
benchmarking, this behavior may be undesirable. In these

cases,
net.inet.ip.portrange.randomized can be used to toggle ran

domization off.
If more than net.inet.ip.portrange.randomcps ports have been

allocated in
the last second, then return to sequential port allocation.

Return to
random allocation only once the current port allocation rate

drops below
net.inet.ip.portrange.randomcps for at least net.inet.ip.portrange.randomtime seconds. The default val

ues for
net.inet.ip.portrange.randomcps and

net.inet.ip.portrange.randomtime are 10 port allocations per second and 45 seconds corresponding

ly.

Multicast Options

IP multicasting is supported only on AF_INET sockets of type

SOCK_DGRAM
and SOCK_RAW, and only on networks where the interface driv

er supports
multicasting.

The IP_MULTICAST_TTL option changes the time-to-live (TTL)

for outgoing
multicast datagrams in order to control the scope of the

multicasts:

u_char ttl; /* range: 0 to 255, default = 1 */
setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, size

of(ttl));

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 be

longs 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.

For hosts with multiple interfaces, each multicast transmis

sion is sent
from the primary network interface. The IP_MULTICAST_IF op

tion overrides
the default for subsequent transmissions from a given sock

et:

struct in_addr addr;
setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(ad

dr));

where "addr" is the local IP address of the desired inter

face or
INADDR_ANY to specify the default interface. An interface's

local IP
address and multicast capability can be obtained via the

SIOCGIFCONF and
SIOCGIFFLAGS ioctls. Normal applications should not need to

use this
option.

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
IP_MULTICAST_LOOP option gives the sender explicit control

over whether
or not subsequent datagrams are looped back:

u_char loop; /* 0 = disable, 1 = enable (default) */
setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, size

of(loop));

This option improves performance for applications that may

have no more
than one instance on a single host (such as a router dae

mon), 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).

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.

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
IP_ADD_MEMBERSHIP option:

struct ip_mreq mreq;
setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, size

of(mreq));

where mreq is the following structure:

struct ip_mreq {

struct in_addr imr_multiaddr; /* IP multicast address of

group */
struct in_addr imr_interface; /* local IP address of in

terface */

}

imr_interface should be set to INADDR_ANY to choose the de

fault multicast
interface, or the IP address of a particular multicast-capa

ble interface
if the host is multihomed. Since FreeBSD 4.4, if the

imr_interface member is within the network range 0.0.0.0/8, it is treated as

an interface
index in the system interface MIB, as per the RIP Version 2

MIB Extension
(RFC-1724).

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 IP_MAX_MEMBERSHIPS (currently 20) memberships

may be added
on a single socket.

To drop a membership, use:

struct ip_mreq mreq;
setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, size

of(mreq));

where mreq contains the same values as used to add the mem

bership. Memberships are dropped when the socket is closed or the pro

cess exits.

Raw IP Sockets

Raw IP sockets are connectionless, and are normally used

with the
sendto(2) and recvfrom(2) calls, though the connect(2) call

may also be
used to fix the destination for future packets (in which

case the read(2)
or recv(2) and write(2) or send(2) system calls may be

used).

If proto is 0, the default protocol IPPROTO_RAW is used for

outgoing
packets, and only incoming packets destined for that proto

col are
received. If proto is non-zero, that protocol number will

be used on
outgoing packets and to filter incoming packets.

Outgoing packets automatically have an IP header prepended

to them (based
on the destination address and the protocol number the sock

et is created
with), unless the IP_HDRINCL option has been set. Incoming

packets are
received with IP header and options intact.

IP_HDRINCL indicates the complete IP header is included with

the data and
may be used only with the SOCK_RAW type.

#include <netinet/in_systm.h>
#include <netinet/ip.h>

int hincl = 1; /* 1 = on, 0 = off */
setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hin

cl));

Unlike previous BSD releases, the program must set all the

fields of the
IP header, including the following:

ip->ip_v = IPVERSION;
ip->ip_hl = hlen >> 2;
ip->ip_id = 0; /* 0 means kernel set appropriate value */
ip->ip_off = offset;

The ip_len and ip_off fields must be provided in host byte

order . All
other fields must be provided in network byte order. See

byteorder(3)
for more information on network byte order. If the ip_id

field is set to
0 then the kernel will choose an appropriate value. If the

header source
address is set to INADDR_ANY, the kernel will choose an ap

propriate
address.

ERRORS

A socket operation may fail with one of the following errors

returned:

[EISCONN] when trying to establish a connection on

a socket

which already has one, or when trying to

send a datagram with the destination address speci

fied and the
socket is already connected;

[ENOTCONN] when trying to send a datagram, but no

destination

address is specified, and the socket has

not been connected;

[ENOBUFS] when the system runs out of memory for an

internal

data structure;

[EADDRNOTAVAIL] when an attempt is made to create a sock

et with a net

work address for which no network inter

face exists.

[EACCES] when an attempt is made to create a raw

IP socket by a

non-privileged process.

The following errors specific to IP may occur when setting

or getting IP
options:

[EINVAL] An unknown socket option name was given.

[EINVAL] The IP option field was improperly

formed; an option

field was shorter than the minimum value

or longer
than the option buffer provided.

The following errors may occur when attempting to send IP

datagrams via a
``raw socket'' with the IP_HDRINCL option set:

[EINVAL] The user-supplied ip_len field was not

equal to the

length of the datagram written to the

socket.

SEE ALSO

getsockopt(2), recv(2), send(2), byteorder(3), icmp(4), in

et(4), intro(4)

HISTORY

The ip protocol appeared in 4.2BSD.

BSD September 26, 2005

BSD