rfc2553.txt

Basic Socket Interface Extensions for IPv6

   related constants defined in this section are obtained by including
   the header <netinet/in.h>.

5.1 Unicast Hop Limit

   A new setsockopt() option controls the hop limit used in outgoing
   unicast IPv6 packets.  The name of this option is IPV6_UNICAST_HOPS,
   and it is used at the IPPROTO_IPV6 layer.  The following example
   illustrates how it is used:

      int  hoplimit = 10;

      if (setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS,
                     (char *) &hoplimit, sizeof(hoplimit)) == -1)
          perror("setsockopt IPV6_UNICAST_HOPS");

   When the IPV6_UNICAST_HOPS option is set with setsockopt(), the
   option value given is used as the hop limit for all subsequent
   unicast packets sent via that socket.  If the option is not set, the
   system selects a default value.  The integer hop limit value (called
   x) is interpreted as follows:




Gilligan, et. al.            Informational                     [Page 18]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


      x < -1:        return an error of EINVAL
      x == -1:       use kernel default
      0 <= x <= 255: use x
      x >= 256:      return an error of EINVAL

   The IPV6_UNICAST_HOPS option may be used with getsockopt() to
   determine the hop limit value that the system will use for subsequent
   unicast packets sent via that socket.  For example:

      int  hoplimit;
      size_t  len = sizeof(hoplimit);

      if (getsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS,
                     (char *) &hoplimit, &len) == -1)
          perror("getsockopt IPV6_UNICAST_HOPS");
      else
          printf("Using %d for hop limit.\n", hoplimit);

5.2 Sending and Receiving Multicast Packets

   IPv6 applications may send UDP multicast packets by simply specifying
   an IPv6 multicast address in the address argument of the sendto()
   function.

   Three socket options at the IPPROTO_IPV6 layer control some of the
   parameters for sending multicast packets.  Setting these options is
   not required: applications may send multicast packets without using
   these options.  The setsockopt() options for controlling the sending
   of multicast packets are summarized below.  These three options can
   also be used with getsockopt().

      IPV6_MULTICAST_IF

         Set the interface to use for outgoing multicast packets.  The
         argument is the index of the interface to use.

         Argument type: unsigned int

      IPV6_MULTICAST_HOPS

         Set the hop limit to use for outgoing multicast packets.  (Note
         a separate option - IPV6_UNICAST_HOPS - is provided to set the
         hop limit to use for outgoing unicast packets.)

         The interpretation of the argument is the same as for the
         IPV6_UNICAST_HOPS option:





Gilligan, et. al.            Informational                     [Page 19]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


           x < -1:        return an error of EINVAL
           x == -1:       use kernel default
           0 <= x <= 255: use x
           x >= 256:      return an error of EINVAL

           If IPV6_MULTICAST_HOPS is not set, the default is 1
           (same as IPv4 today)

         Argument type: int

      IPV6_MULTICAST_LOOP

         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 looped back by the IP layer for local delivery if
         this option is set to 1.  If this option is set to 0 a copy
         is not looped back.  Other option values return an error of
         EINVAL.

         If IPV6_MULTICAST_LOOP is not set, the default is 1 (loopback;
         same as IPv4 today).

         Argument type: unsigned int

   The reception of multicast packets is controlled by the two
   setsockopt() options summarized below.  An error of EOPNOTSUPP is
   returned if these two options are used with getsockopt().

      IPV6_JOIN_GROUP

         Join a multicast group on a specified local interface.  If the
         interface index is specified as 0, the kernel chooses the local
         interface.  For example, some kernels look up the multicast
         group in the normal IPv6 routing table and using the resulting
         interface.

         Argument type: struct ipv6_mreq

      IPV6_LEAVE_GROUP

         Leave a multicast group on a specified interface.

         Argument type: struct ipv6_mreq

   The argument type of both of these options is the ipv6_mreq structure,
   defined as a result of including the <netinet/in.h> header;





Gilligan, et. al.            Informational                     [Page 20]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   struct ipv6_mreq {
       struct in6_addr ipv6mr_multiaddr; /* IPv6 multicast addr */
       unsigned int    ipv6mr_interface; /* interface index */
   };

   Note that to receive multicast datagrams a process must join the
   multicast group and bind the UDP port to which datagrams will be
   sent.  Some processes also bind the multicast group address to the
   socket, in addition to the port, to prevent other datagrams destined
   to that same port from being delivered to the socket.

6. Library Functions

   New library functions are needed to perform a variety of operations
   with IPv6 addresses.  Functions are needed to lookup IPv6 addresses
   in the Domain Name System (DNS).  Both forward lookup (nodename-to-
   address translation) and reverse lookup (address-to-nodename
   translation) need to be supported.  Functions are also needed to
   convert IPv6 addresses between their binary and textual form.

   We note that the two existing functions, gethostbyname() and
   gethostbyaddr(), are left as-is.  New functions are defined to handle
   both IPv4 and IPv6 addresses.

6.1 Nodename-to-Address Translation

   The commonly used function gethostbyname() is inadequate for many
   applications, first because it provides no way for the caller to
   specify anything about the types of addresses desired (IPv4 only,
   IPv6 only, IPv4-mapped IPv6 are OK, etc.), and second because many
   implementations of this function are not thread safe.  RFC 2133
   defined a function named gethostbyname2() but this function was also
   inadequate, first because its use required setting a global option
   (RES_USE_INET6) when IPv6 addresses were required, and second because
   a flag argument is needed to provide the caller with additional
   control over the types of addresses required.

   The following function is new and must be thread safe:

   #include <sys/socket.h>
   #include <netdb.h>

   struct hostent *getipnodebyname(const char *name, int af, int flags
                                       int *error_num);

   The name argument can be either a node name or a numeric address
   string (i.e., a dotted-decimal IPv4 address or an IPv6 hex address).
   The af argument specifies the address family, either AF_INET or



Gilligan, et. al.            Informational                     [Page 21]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   AF_INET6. The error_num value is returned to the caller, via a
   pointer, with the appropriate error code in error_num, to support
   thread safe error code returns.  error_num will be set to one of the
   following values:

      HOST_NOT_FOUND

         No such host is known.

      NO_ADDRESS

         The server recognised the request and the name but no address is
         available.  Another type of request to the name server for the
         domain might return an answer.

      NO_RECOVERY

         An unexpected server failure occurred which cannot be recovered.

      TRY_AGAIN

         A temporary and possibly transient error occurred, such as a
         failure of a server to respond.

   The flags argument specifies the types of addresses that are searched
   for, and the types of addresses that are returned.  We note that a
   special flags value of AI_DEFAULT (defined below) should handle most
   applications.

   That is, porting simple applications to use IPv6 replaces the call

      hptr = gethostbyname(name);

   with

      hptr = getipnodebyname(name, AF_INET6, AI_DEFAULT, &error_num);

   and changes any subsequent error diagnosis code to use error_num
   instead of externally declared variables, such as h_errno.

   Applications desiring finer control over the types of addresses
   searched for and returned, can specify other combinations of the
   flags argument.








Gilligan, et. al.            Informational                     [Page 22]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   A flags of 0 implies a strict interpretation of the af argument:

      - If flags is 0 and af is AF_INET, then the caller wants only
        IPv4 addresses.  A query is made for A records.  If successful,
        the IPv4 addresses are returned and the h_length member of the
        hostent structure will be 4, else the function returns a NULL
        pointer.

      -  If flags is 0 and if af is AF_INET6, then the caller wants only
        IPv6 addresses.  A query is made for AAAA records.  If
        successful, the IPv6 addresses are returned and the h_length
        member of the hostent structure will be 16, else the function
        returns a NULL pointer.

   Other constants can be logically-ORed into the flags argument, to
   modify the behavior of the function.

      - If the AI_V4MAPPED flag is specified along with an af of
        AF_INET6, then the caller will accept IPv4-mapped IPv6
        addresses.  That is, if no AAAA records are found then a query
        is made for A records and any found are returned as IPv4-mapped
        IPv6 addresses (h_length will be 16).  The AI_V4MAPPED flag is
        ignored unless af equals AF_INET6.

      - The AI_ALL flag is used in conjunction with the AI_V4MAPPED
        flag, and is only used with the IPv6 address family.  When AI_ALL
        is logically or'd with AI_V4MAPPED flag then the caller wants
        all addresses: IPv6 and IPv4-mapped IPv6.  A query is first made
        for AAAA records and if successful, the IPv6 addresses are
        returned. Another query is then made for A records and any found
        are returned as IPv4-mapped IPv6 addresses. h_length will be 16.
        Only if both queries fail does the function return a NULL pointer.
        This flag is ignored unless af equals AF_INET6.

      - The AI_ADDRCONFIG flag specifies that a query for AAAA records
        should occur only if the node has at least one IPv6 source
        address configured and a query for A records should occur only
        if the node has at least one IPv4 source address configured.

        For example, if the node has no IPv6 source addresses
        configured, and af equals AF_INET6, and the node name being
        looked up has both AAAA and A records, then:

            (a) if only AI_ADDRCONFIG is specified, the function
                returns a NULL pointer;
            (b) if AI_ADDRCONFIG | AI_V4MAPPED is specified, the A
                records are returned as IPv4-mapped IPv6 addresses;




Gilligan, et. al.            Informational                     [Page 23]

RFC 2553       Basic Socket Interface Extensions for IPv6     March 1999


   The special flags value of AI_DEFAULT is defined as

      #define  AI_DEFAULT  (AI_V4MAPPED | AI_ADDRCONFIG)

   We noted that the getipnodebyname() function must allow the name
   argument to be either a node name or a literal address string (i.e.,
   a dotted-decimal IPv4 address or an IPv6 hex address).  This saves
   applications from having to call inet_pton() to handle literal
   address strings.

   There are four scenarios based on the type of literal address string
   and the value of the af argument.

   The two simple cases are:

   When name is a dotted-decimal IPv4 address and af equals AF_INET, or
   when name is an IPv6 hex address and af equals AF_INET6.  The members
   of the returned hostent structure are: h_name points to a copy of the