IP(7P)IP(7P)NAMEIP - Internet Protocol
SYNOPSISDESCRIPTIONIP is the network-layer protocol used by the Internet protocol family.
It encapsulates TCP and UDP messages into datagrams to be transmitted
by the network interface. Normally, applications do not need to inter‐
face directly to IP. However, certain multicast socket options are
controlled by passing options to the protocol level through a UDP
socket, and IP Type of Service is controlled by passing an option to
the protocol level through either a TCP or UDP socket. (See the get‐
sockopt(2) manual page.)
The following socket options are defined in the include file The type
of the variable pointed to by the optval parameter is indicated in
parentheses. The data types and are defined in
Sets the IP Type of Service.
Allowable values for optval are 4 for
high reliability, 8 for high through‐
put, and 16 for low delay. Other val‐
ues will not return an error, but may
have unpredictable results. Default:
zero.
Requests that the system join a multicast group in "exclude"
mode.
Requests that the system join a multicast group in "exclude"
mode.
Allows the system to leave a multicast group.
Allows the system to leave a multicast group.
Adds a source address to the list of blocked sources
for a multicast group in "exclude"
mode.
Adds a source address to the list of blocked sources
for a multicast group in "exclude"
mode.
Removes a source address from the list of blocked sources
for a multicast group in "exclude"
mode.
Removes a source address from the list of blocked sources
for a multicast group in "exclude"
mode.
Adds a source address to the list of allowed sources
for a multicast group in "include"
mode, joining the group in "include"
mode if not already joined.
Adds a source address to the list of allowed sources
for a multicast group in "include"
mode, joining the group in "include"
mode if not already joined.
Removes a source address from the list of allowed sources
for a multicast group in "include"
mode, leaving the group when the last
source is removed.
Removes a source address from the list of allowed sources
for a multicast group in "include"
mode, leaving the group when the last
source is removed.
Specifies a network interface other than the default to be
used when sending multicast datagrams
through this socket. Default: multi‐
cast datagrams are sent from the inter‐
face associated with the specific mul‐
ticast group, with the default multi‐
cast route or with the default route.
boolean) Enables or disables loopback in the IP
layer for multicast datagrams sent
through this socket. The value of the
variable pointed to by optval is zero
(disable) or non-zero (enable). This
option is provided for compatibility
only. Normally, multicast datagrams
are always looped back if the system
has joined the group. See below.
Default: enabled.
Specifies the time-to-live value for multicast datagrams
sent through this socket. The value of
the variable pointed to by optval can
be zero through 255. Default: one.
An application joins a multicast group on a network interface in order
to receive multicast datagrams sent on the network to which that inter‐
face connects. An application can join up to multicast groups on each
socket. is defined in However, each network interface may impose a
smaller system-wide limit because of interface resource limitations and
because the system uses some link-layer multicast addresses.
The application must also bind to the destination port number in order
to receive datagrams that are sent to that port number. If the appli‐
cation binds to the address it may receive all datagrams that are sent
to the port number. If the application binds to a multicast group
address, it may receive only datagrams sent to that group and port num‐
ber. It is not necessary to join a multicast group in order to send
datagrams to it.
For each multicast group that an application joins on a given socket
and network interface, there is an associated filter mode and source
list. The filter mode can be "exclude" mode or "include" mode. The
source list is a set of IP addresses which will be compared to the
source addresses of received multicast datagrams.
An application uses "exclude" mode when it wants to block reception of
multicast datagrams from a specific set of sources, while allowing mul‐
ticast datagrams from all other sources. For groups in "exclude" mode,
the source list may be empty, thus allowing reception of multicast
datagrams from all sources.
An application uses "include" mode when it wants to allow reception of
multicast datagrams from a specific set of sources, while blocking mul‐
ticast datagrams from all other sources. For groups in "include" mode,
the source list needs to contain at least one member in order for the
application to stay joined to the group; removing the last address from
an "include" mode source list will cause the application to leave the
group.
and request that the system join a multicast group on the specified
interface. The group is joined in "exclude" mode, with an empty source
list. The field holds the IPv4 address of a local interface, or The
field holds the interface index of a local interface, or zero. If the
interface address is or if the interface index is zero, the system
joins the specified group on the interface from which datagrams for
that group would be sent, based on the routing configuration. For
example:
struct ip_mreq mreq;
mreq.imr_multiaddr.s_addr = inet_addr("224.1.2.3");
mreq.imr_interface.s_addr = INADDR_ANY;
setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));
struct group_req gr;
struct sockaddr_in *sin;
sin = (struct sockaddr_in *)&gr.gr_group;
bzero(sin, sizeof(*sin));
sin->sin_family = AF_INET;
sin->sin_addr.s_addr = inet_addr("224.1.2.3");
gr.gr_interface = 0;
setsockopt(s, IPPROTO_IP, MCAST_JOIN_GROUP, &gr, sizeof(gr));
and allow the system to leave a multicast group. The field holds the
IPv4 address of a local interface, or The field holds the interface
index of a local interface, or zero. If the interface address is or if
the interface index is zero, the system chooses a multicast group by
matching the multicast address only. For example:
struct ip_mreq mreq;
mreq.imr_multiaddr.s_addr = inet_addr("224.1.2.3");
mreq.imr_interface.s_addr = INADDR_ANY;
setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
struct group_req gr;
struct sockaddr_in *sin;
sin = (struct sockaddr_in *)&gr.gr_group;
bzero(sin, sizeof(*sin));
sin->sin_family = AF_INET;
sin->sin_addr.s_addr = inet_addr("224.1.2.3");
gr.gr_interface = 0;
setsockopt(s, IPPROTO_IP, MCAST_LEAVE_GROUP, &gr, sizeof(gr));
and add a source address to the list of sources being blocked. and
remove a source address from the list of sources being blocked. The
group must already be joined, and must be in "exclude" mode. The field
holds the IPv4 address of a local interface, or The field holds the
interface index of a local interface, or zero. If the interface
address is or if the interface index is zero, the system chooses a mul‐
ticast group by matching the multicast address only. For example:
struct ip_mreq_source imr;
imr.imr_multiaddr.s_addr = inet_addr("224.1.2.3");
imr.imr_sourceaddr.s_addr = inet_addr("10.4.5.6");
imr.imr_interface.s_addr = INADDR_ANY;
setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &imr, sizeof(imr));
setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &imr, sizeof(imr));
struct group_source_req gsr;
struct sockaddr_in *sin;
sin = (struct sockaddr_in *)&gsr.gsr_group;
bzero(sin, sizeof(*sin));
sin->sin_family = AF_INET;
sin->sin_addr.s_addr = inet_addr("224.1.2.3");
sin = (struct sockaddr_in *)&gsr.gsr_source;
bzero(sin, sizeof(*sin));
sin->sin_family = AF_INET;
sin->sin_addr.s_addr = inet_addr("10.4.5.6");
gsr.gsr_interface = 0;
setsockopt(s, IPPROTO_IP, MCAST_BLOCK_SOURCE, &gsr, sizeof(gsr));
setsockopt(s, IPPROTO_IP, MCAST_UNBLOCK_SOURCE, &gsr, sizeof(gsr));
and add a source address to the list of allowed sources for a multicast
group in "include" mode, joining the group in "include" mode if not
already joined. and remove a source address from the list of allowed
sources for a multicast group in "include" mode, leaving the group if
the last source is being removed. The field holds the IPv4 address of
a local interface, or The field holds the interface index of a local
interface, or zero. If the interface address is or the interface index
is zero, the behavior depends on whether the group is being joined. If
the group is being joined, the system joins the specified group on the
interface from which datagrams for that group would be sent, based on
the routing configuration; otherwise, the system chooses a multicast
group by matching the multicast address only. For example:
struct ip_mreq_source imr;
imr.imr_multiaddr.s_addr = inet_addr("224.1.2.3");
imr.imr_sourceaddr.s_addr = inet_addr("10.4.5.6");
imr.imr_interface.s_addr = INADDR_ANY;
setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &imr, sizeof(imr));
setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &imr, sizeof(imr));
struct group_source_req gsr;
struct sockaddr_in *sin;
sin = (struct sockaddr_in *)&gsr.gsr_group;
bzero(sin, sizeof(*sin));
sin->sin_family = AF_INET;
sin->sin_addr.s_addr = inet_addr("224.1.2.3");
sin = (struct sockaddr_in *)&gsr.gsr_source;
bzero(sin, sizeof(*sin));
sin->sin_family = AF_INET;
sin->sin_addr.s_addr = inet_addr("10.4.5.6");
gsr.gsr_interface = 0;
setsockopt(s, IPPROTO_IP, MCAST_JOIN_SOURCE_GROUP, &gsr, sizeof(gsr));
setsockopt(s, IPPROTO_IP, MCAST_LEAVE_SOURCE_GROUP, &gsr, sizeof(gsr));
specifies a local network interface to be used when sending multicast
datagrams through this socket. For example:
#include <arpa/inet.h>
struct in_addr addr;
addr.s_addr = inet_addr("192.1.2.3");
setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));
Normally, applications do not need to specify the interface. By
default, multicast datagrams are sent from the interface specified by
the routing configuration, namely the interface associated with the
specific multicast group, with the default multicast route or with the
default route. If is set to the address the default interface is
selected. Otherwise, should be the IP address of a local interface.
enables or disables loopback for multicast datagrams sent through this
socket. For example:
unsigned char loop = 1;
setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));
Note that the type of the optval parameter is instead of which is com‐
mon for boolean socket options. This option is provided for compati‐
bility only. Normally, if a multicast datagram is sent to a group that
the system has joined, a copy of the datagram is always looped back and
delivered to any applications that are bound to the destination port.
See below.
controls the scope a multicast by setting the time-to-live value for
multicast datagrams sent through this socket. For example:
unsigned char ttl = 64;
setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));
Note that the type of optval parameter is instead which is common for
socket options. By default, the time-to-live field (TTL) is one, which
limits the multicast to the local network. If the TTL is zero, the
multicast is limited to the local system (loopback). If the TTL is
two, the multicast can be forwarded through at most one gateway; and so
forth. Multicast datagrams can be forwarded to other networks only if
there are special multicast routers on the local and intermediate net‐
works.
DEPENDENCIES
The behavior of depends on the network driver and interface card. Nor‐
mally, loopback cannot be disabled, even if is set to zero, because it
occurs in the driver or in the network interface. However, if the out‐
bound interface is (127.0.0.1), or if is set to zero, setting to zero
will disable loopback for multicast datagrams sent through the socket.
ERRORS
One of the following errors may be returned if a call to or fails.
The specified multicast group has been joined
already on socket.
The specified IP address is not a local interface address;
or there is no route for the specified
multicast address; or the specified mul‐
ticast group has not been joined.
The parameter level is not or optval is the NULL
address; or the specified multicast
address is not valid; or the specified
source address is not valid; or the spec‐
ified interface index is not valid; or
the option is not valid for the current
filter mode.
Insufficient memory is available for internal
system data structures; or the number of
sources in a multicast source filter
exceeds the maximum number of sources
allowed, as determined by the ndd tunable
parameters and
The parameter optname is not a valid socket option for
the level.
The socket type is not
An attempt to join more than
multicast groups on a socket.
AUTHOR
The socket interfaces to IP were developed by the University of Cali‐
fornia, Berkeley. Multicast extensions were developed by the Stanford
University.
SEE ALSOndd(1M), bind(2), getsockopt(2), recv(2), send(2), socket(2),
getipv4sourcefilter(3N), getsourcefilter(3N), if_nameindex(3N),
setipv4sourcefilter(3N), setsourcefilter(3N), inet(7F).
RFC 3678 Socket Interface Extensions for Multicast Source Filters.
IP(7P)
