IP(7P)

DESCRIPTION

IP 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 interface directly to IP. However, certain multicast socket options are controlled by passing options to the IPPROTO_IP protocol level through a UDP socket, and IP Type of Service is controlled by passing an option to the IPPROTO_IP protocol level through either a TCP or UDP socket. (See the getsockopt(2) manual page.)

The following socket options are defined in the include file <netinet/in.h>. The type of the variable pointed to by the optval parameter is indicated in parentheses. The data types struct ip_mreq and struct in_addr are defined in <netinet/in.h>.

IP_ADD_MEMBERSHIP requests that the system join a multicast group on the specified interface. For example:

A system must join a group on an interface in order to receive multicast datagrams sent on the network to which that interface connects. If imr_interface is set to INADDR_ANY, the system joins the specified group on the interface that datagrams for that group would be sent from, based the routing configuration. Otherwise, imr_interface should be the IP address of a local interface. An application can join up to IP_MAX_MEMBERSHIPS multicast groups on each socket. IP_MAX_MEMBERSHIPS is defined in <netinet/in.h>. 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 application binds to the address INADDR_ANY, 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 number. It is not necessary to join a multicast group in order to send datagrams to it.

IP_DROP_MEMBERSHIP allows the system to leave a multicast group. For example:

The system remains a member of the multicast group until the last socket that joined the group is closed or has dropped membership in the group.

IP_MULTICAST_IF specifies a local network interface to be used when sending multicast datagrams through this socket. For example:

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 addr is set to the address INADDR_ANY, the default interface is selected. Otherwise, addr should be the IP address of a local interface.

IP_MULTICAST_LOOP enables or disables loopback for multicast datagrams sent through this socket. For example:

Note that the type of the optval parameter is unsigned char instead of int, which is common for boolean socket options. This option is provided for compatibility 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 DEPENDENCIES below.

IP_MULTICAST_TTL controls the scope a multicast by setting the time-to-live value for multicast datagrams sent through this socket. For example:

Note that the type of optval parameter is unsigned char instead int, 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 networks.

DEPENDENCIES

The behavior of IP_MULTICAST_LOOP depends on the network driver and interface card. Normally, loopback cannot be disabled, even if IP_MULTICAST_LOOP is set to zero, because it occurs in the driver or in the network interface. However, if the outbound interface is lo0 (127.0.0.1), or if IP_MULTICAST_TTL is set to zero, setting IP_MULTICAST_LOOP 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 setsockopt() or getsockopt() fails.

AUTHOR

The socket interfaces to IP were developed by the University of California, Berkeley. Multicast extensions were developed by the Stanford University.

SEE ALSO

bind(2), getsockopt(2), recv(2), send(2), socket(2), inet(7F).