21.7 mcast_join and Related Functions

Although the multicast socket options for IPv4 are similar to the multicast socket options for IPv6, there are enough differences that protocol-independent code using multicasting becomes complicated with lots of #ifdefs. A better solution is to hide the differences within the following eight functions:

#include "unp.h"
int mcast_join(int sockfd, const struct sockaddr *grp, socklen_t grplen, const char *ifname, u_int ifindex);
int mcast_leave(int sockfd, const struct sockaddr *grp, socklen_t grplen);
int mcast_block_source(int sockfd, const struct sockaddr *src, socklen_t srclen, const struct sockaddr *grp, socklen_t grplen);
int mcast_unblock_source(int sockfd, const struct sockaddr *src, socklen_t srclen, const struct sockaddr *grp, socklen_t grplen);
int mcast_join_source_group(int sockfd, const struct sockaddr *src, socklen_t srclen, const struct sockaddr *grp, socklen_t grplen, const char *ifname, u_int ifindex);
int mcast_leave_source_group(int sockfd, const struct sockaddr *src, socklen_t srclen, const struct sockaddr *grp, socklen_t grplen);
int mcast_set_if(int sockfd, const char *ifname, u_int ifindex);
int mcast_set_loop(int sockfd, int flag);
int mcast_set_ttl(int sockfd, int ttl);
All above return: 0 if OK, –1 on error
int mcast_get_if(int sockfd);
Returns: non-negative interface index if OK, –1 on error
int mcast_get_loop(int sockfd);
Returns: current loopback flag if OK, –1 on error
int mcast_get_ttl(int sockfd);
Returns: current TTL or hop limit if OK, –1 on error

mcast_join joins the any-source multicast group whose IP address is contained within the socket address structure pointed to by grp, and whose length is specified by grplen. We can specify the interface on which to join the group by either the interface name (a non-null ifname) or a nonzero interface index (ifindex). If neither is specified, the kernel chooses the interface on which the group is joined. Recall that with IPv6, the interface is specified to the socket option by its index. If a name is specified for an IPv6 socket, we call if_nametoindex to obtain the index. With the IPv4 socket option, the interface is specified by its unicast IP address. If a name is specified for an IPv4 socket, we call ioctl with a request of SIOCGIFADDR to obtain the unicast IP address for the interface. If an index is specified for an IPv4 socket, we first call if_indextoname to obtain the name and then process the name as just described.

An interface name, such as le0 or ether0, is normally the way users specify interfaces, and not with either the IP address or the index. tcpdump, for example, is one of the few programs that lets the user specify an interface, and its -i option takes an interface name as the argument.

mcast_leave leaves the multicast group whose IP address is contained within the socket address structure pointed to by grp. Note that mcast_leave does not take an interface specification; it always deletes the first matching membership. This simplifies the library API, but means that programs that require direct control of per-interface membership need to use the setsockopt API directly.

mcast_block_source blocks reception on the given socket of the source and group whose IP addresses are contained within the socket address structures pointed to by src and grp, respectively, and whose lengths are specified by srclen and grplen. mcast_join must have already been called on this socket for the given group.

mcast_unblock_source unblocks reception of traffic from the given source to the given group. The src, srclen, grp, and grplen arguments must be the same as a previous call to mcast_block_source.

mcast_join_source_group joins the source-specific group where the source and group IP addresses are contained within the socket address structures pointed to by src and grp, respectively, and whose lengths are specified by srclen and grplen. We can specify the interface on which to join the group by either the interface name (a non-null ifname) or a nonzero interface index (ifindex). If neither is specified, the kernel chooses the interface on which the group is joined.

mcast_leave_source_group leaves the source-specific multicast group whose source and group IP addresses are contained within the socket address structures pointed to by src and grp, respectively, and whose lengths are specified by srclen and grplen. As with mcast_leave, mcast_leave_source_group does not take an interface specification; it always deletes the first matching membership.

mcast_set_if sets the default interface index for outgoing multicast datagrams. If ifindex is greater than 0, then it specifies the interface index; otherwise, if ifname is nonnull, then it specifies the interface name. For IPv6, the name is mapped to an index using if_nametoindex. For IPv4, the mapping from either a name or an index into the interface's unicast IP address is done as described for mcast_join.

mcast_set_loop sets the loopback option to either 0 or 1, and mcast_set_ttl sets either the IPv4 TTL or the IPv6 hop limit. The three mcast_get_XXX functions return the corresponding value.

Example: mcast_join Function

Figure 21.10 shows the first third of our mcast_join function. This third shows how straightforward the protocol-independent API can be.

Handle index

9–17 If the caller supplied an index, then we just use it directly. Otherwise, if the caller supplied an interface name, the index is obtained by calling if_nametoindex. Otherwise, the interface is set to 0, telling the kernel to choose the interface.

Copy address and call setsockopt

18–22 The caller's socket address is copied directly into the request's group field. Recall that the group field is a sockaddr_storage, so it is big enough to handle any socket address type the system supports. However, to guard against buffer overruns caused by sloppy coding, we check the sockaddr size and return EINVAL if it is too large.

23–24 setsockopt performs the join. The level argument to setsockopt is determined using the family of the group address and our family_to_level function. Some systems support a mismatch between level and the socket's address family, for instance, using IPPROTO_IP with MCAST_JOIN_GROUP, even with an AF_INET6 socket, but not all do, so we turn the address family into the appropriate level. We do not show this trivial function, but the source code is freely available (see the Preface).

Figure 21.10 Join a multicast group: IP version-independent.

lib/mcast_join.c

 1 #include    "unp.h"
 2 #include    <net/if.h>

 3 int
 4 mcast_join(int sockfd, const SA *grp, socklen_t grplen,
 5            const char *ifname, u_int ifindex)
 6 {
 7 #ifdef MCAST_JOIN_GROUP
 8     struct group_req req;
 9     if (ifindex > 0) {
10         req.gr_interface = ifindex;
11     } else if (ifname != NULL) {
12         if ( (req.gr_interface = if_nametoindex(ifname)) == 0) {
13             errno = ENXIO;      /* i/f name not found */
14             return (-1);
15         }
16     } else
17         req.gr_interface = 0;
18     if (grplen > sizeof(req.gr_group)) {
19         errno = EINVAL;
20         return -1;
21     }
22     memcpy(&req.gr_group, grp, grplen);
23     return (setsockopt(sockfd, family_to_level(grp->sa_family),
24                        MCAST_JOIN_GROUP, &req, sizeof(req)));
25 #else

Figure 21.11 shows the second third of mcast_join, which handles IPv4 sockets.

Handle index

33–38 The IPv4 multicast address in the socket address structure is copied into an ip_mreq structure. If an index was specified, if_indextoname is called, storing the name into our ifreq structure. If this succeeds, we branch ahead to issue the ioctl.

Handle name

39–46 The caller's name is copied into an ifreq structure, and an ioctl of SIOCGIFADDR returns the unicast address associated with this name. Upon success the IPv4 address is copied into the imr_interface member of the ip_mreq structure.

Specify default

47–48 If an index was not specified and a name was not specified, the interface is set to the wildcard address, telling the kernel to choose the interface.

49–50 setsockopt performs the join.

Figure 21.11 Join a multicast group: IPv4 socket.

lib/mcast_join.c

26   switch (grp->sa_family) {
27   case AF_INET:{
28           struct ip_mreq mreq;
29           struct ifreq ifreq;

30           memcpy(&mreq.imr_multiaddr,
31                  &((const struct sockaddr_in *) grp)->sin_addr,
32                  sizeof(struct in_addr));

33           if (ifindex > 0) {
34               if (if_indextoname(ifindex, ifreq.ifr_name) == NULL) {
35                   errno = ENXIO; /*  i/f index not found */
36                   return (-1);
37               }
38               goto doioctl;
39           } else if (ifname != NULL) {
40               strncpy(ifreq.ifr_name, ifname, IFNAMSIZ);
41             doioctl:
42               if (ioctl(sockfd, SIOCGIFADDR, &ifreq) < 0)
43                   return (-1);
44               memcpy(&mreq.imr_interface,
45                      &((struct sockaddr_in *) &ifreq.ifr_addr)->sin_addr,
46                      sizeof(struct in_addr));
47           } else
48               mreq.imr_interface.s_addr = htonl(INADDR_ANY);

49           return (setsockopt(sockfd, IPPROTO_IP, IP_ADD_MEMBERSHIP,
50                              &mreq, sizeof(mreq)));
51      }

The final portion of the function, which handles IPv6 sockets, is shown in Figure 21.12.

Copy address

55–57 First the IPv6 multicast address is copied from the socket address structure into the ipv6_mreq structure.

Handle index, name, or default

58–66 If an index was specified, it is stored in the ipv6mr_interface member; if a name was specified, the index is obtained by calling if_nametoindex; otherwise, the interface index is set to 0 for setsockopt, telling the kernel to choose the interface.

67–68 The group is joined.

Figure 21.12 Join a multicast group: IPv6 socket.

lib/mcast_join.c

52 #ifdef  IPV6
53     case AF_INET6:{
54             struct ipv6_mreq mreq6;

55             memcpy(&mreq6.ipv6mr_multiaddr,
56                    &((const struct sockaddr_in6 *) grp) ->sin6_addr,
57                    sizeof(struct in6_addr));

58             if (ifindex > 0) {
59                 mreq6.ipv6mr_interface = ifindex;
60             } else if (ifname != NULL) {
61                 if ( (mreq6.ipv6mr_interface = if_nametoindex(ifname)) == 0) {
62                     errno = ENXIO;  /* i/f name not found */
63                     return (-1);
64                 }
65             } else
66                 mreq6.ipv6mr_interface = 0;

67             return (setsockopt(sockfd, IPPROTO_IPV6, IPV6_JOIN_GROUP,
68                                &mreq6, sizeof(mreq6)));
69         }
70 #endif

71     default:
72         errno = EAFNOSUPPORT;
73         return (-1);
74     }
75 #endif
76 }

Example: mcast_set_loop Function

Figure 21.13 shows our mcast_set_loop function.

Since the argument is a socket descriptor and not a socket address structure, we call our sockfd_to_family function to obtain the address family of the socket. The appropriate socket option is set.

We do not show the source code for all remaining mcast_XXX functions, but it is freely available (see the Preface).

Figure 21.13 Set the multicast loopback option.

lib/mcast_set_loop.c

 1 #include    "unp.h"

 2 int
 3 mcast_set_loop(int sockfd, int onoff)
 4 {
 5     switch (sockfd_to_family(sockfd)) {
 6     case AF_INET:{
 7             u_char  flag;

 8             flag = onoff;
 9             return (setsockopt(sockfd, IPPROTO_IP, IP_MULTICAST_LOOP,
10                                &flag, sizeof(flag)));
11         }

12 #ifdef  IPV6
13     case AF_INET6:{
14             u_int   flag;

15             flag = onoff;
16             return (setsockopt(sockfd, IPPROTO_IPV6, IPV6_MULTICAST_LOOP,
17                                &flag, sizeof(flag)));
18         }
19 #endif

20     default:
21         errno = EAFNOSUPPORT;
22         return (-1);
23     }
24 }