Tech-invite3GPPspecsGlossariesIETFRFCsGroupsSIPABNFsWorld Map

RFC 2292


Advanced Sockets API for IPv6

Part 3 of 3, p. 42 to 67
Prev RFC Part


prevText      Top      Up      ToC       Page 42 
7.  Destination Options

   A variable number of Destination options can appear in one or more
   Destination option headers.  As defined in [RFC-1883], a Destination
   options header appearing before a Routing header is processed by the
   first destination plus any subsequent destinations specified in the
   Routing header, while a Destination options header appearing after a
   Routing header is processed only by the final destination.  As with
   the Hop-by-Hop options, each option in a Destination options header
   is TLV-encoded with a type, length, and value.

   Today no Destination options are defined for IPv6 [RFC-1883],
   although proposals exist to use Destination options with mobility and

7.1.  Receiving Destination Options

   To receive Destination options the application must enable the
   IPV6_DSTOPTS socket option:

       int  on = 1;
       setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on));

   All the Destination options appearing before a Routing header are
   returned as one ancillary data object described by a cmsghdr
   structure and all the Destination options appearing after a Routing
   header are returned as another ancillary data object described by a
   cmsghdr structure.  For these ancillary data objects, the cmsg_level

Top      Up      ToC       Page 43 
   member will be IPPROTO_IPV6 and the cmsg_type member will be
   IPV6_HOPOPTS.  These options are then processed by calling the
   inet6_option_next() and inet6_option_find() functions.

7.2.  Sending Destination Options

   To send one or more Destination options, the application just
   specifies them as ancillary data in a call to sendmsg().  No socket
   option need be set.

   As described earlier, one set of Destination options can appear
   before a Routing header, and one set can appear after a Routing
   header.  Each set can consist of one or more options.

   Normally all the Destination options in a set are specified by a
   single ancillary data object, since each option is itself TLV-
   encoded.  Multiple ancillary data objects, each containing one or
   more Destination options, can also be specified, in which case the
   kernel will combine all the Destination options in the set into a
   single Destination extension header.  But it should be more efficient
   to use a single ancillary data object to describe all the Destination
   options in a set.  The cmsg_level member is set to IPPROTO_IPV6 and
   the cmsg_type member is set to IPV6_DSTOPTS.  The option is normally
   constructed using the inet6_option_init(), inet6_option_append(), and
   inet6_option_alloc() functions.

   Additional errors may be possible from sendmsg() if the specified
   option is in error.

8.  Routing Header Option

   Source routing in IPv6 is accomplished by specifying a Routing header
   as an extension header.  There can be different types of Routing
   headers, but IPv6 currently defines only the Type 0 Routing header
   [RFC-1883].  This type supports up to 23 intermediate nodes.  With
   this maximum number of intermediate nodes, a source, and a
   destination, there are 24 hops, each of which is defined as a strict
   or loose hop.

   Source routing with IPv4 sockets API (the IP_OPTIONS socket option)
   requires the application to build the source route in the format that
   appears as the IPv4 header option, requiring intimate knowledge of
   the IPv4 options format.  This IPv6 API, however, defines eight
   functions that the application calls to build and examine a Routing
   header.  Four functions build a Routing header:

   inet6_rthdr_space()    - return #bytes required for ancillary data
   inet6_rthdr_init()     - initialize ancillary data for Routing header

Top      Up      ToC       Page 44 
   inet6_rthdr_add()      - add IPv6 address & flags to Routing header
   inet6_rthdr_lasthop()  - specify the flags for the final hop

   Four functions deal with a returned Routing header:

    inet6_rthdr_reverse()  - reverse a Routing header
    inet6_rthdr_segments() - return #segments in a Routing header
    inet6_rthdr_getaddr()  - fetch one address from a Routing header
    inet6_rthdr_getflags() - fetch one flag from a Routing header

   The function prototypes for these functions are all in the
   <netinet/in.h> header.

   To receive a Routing header the application must enable the
   IPV6_RTHDR socket option:

       int  on = 1;
       setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on));

   To send a Routing header the application just specifies it as
   ancillary data in a call to sendmsg().

   A Routing header is passed between the application and the kernel as
   an ancillary data object.  The cmsg_level member has a value of
   IPPROTO_IPV6 and the cmsg_type member has a value of IPV6_RTHDR.  The
   contents of the cmsg_data[] member is implementation dependent and
   should not be accessed directly by the application, but should be
   accessed using the eight functions that we are about to describe.

   The following constants are defined in the <netinet/in.h> header:

    #define IPV6_RTHDR_LOOSE     0 /* this hop need not be a neighbor */
    #define IPV6_RTHDR_STRICT    1 /* this hop must be a neighbor */

    #define IPV6_RTHDR_TYPE_0    0 /* IPv6 Routing header type 0 */

   When a Routing header is specified, the destination address specified
   for connect(), sendto(), or sendmsg() is the final destination
   address of the datagram.  The Routing header then contains the
   addresses of all the intermediate nodes.

8.1.  inet6_rthdr_space

       size_t inet6_rthdr_space(int type, int segments);

   This function returns the number of bytes required to hold a Routing
   header of the specified type containing the specified number of

Top      Up      ToC       Page 45 
   segments (addresses).  For an IPv6 Type 0 Routing header, the number
   of segments must be between 1 and 23, inclusive.  The return value
   includes the size of the cmsghdr structure that precedes the Routing
   header, and any required padding.

   If the return value is 0, then either the type of the Routing header
   is not supported by this implementation or the number of segments is
   invalid for this type of Routing header.

   (Note: This function returns the size but does not allocate the space
   required for the ancillary data.  This allows an application to
   allocate a larger buffer, if other ancillary data objects are
   desired, since all the ancillary data objects must be specified to
   sendmsg() as a single msg_control buffer.)

8.2.  inet6_rthdr_init

       struct cmsghdr *inet6_rthdr_init(void *bp, int type);

   This function initializes the buffer pointed to by bp to contain a
   cmsghdr structure followed by a Routing header of the specified type.
   The cmsg_len member of the cmsghdr structure is initialized to the
   size of the structure plus the amount of space required by the
   Routing header.  The cmsg_level and cmsg_type members are also
   initialized as required.

   The caller must allocate the buffer and its size can be determined by
   calling inet6_rthdr_space().

   Upon success the return value is the pointer to the cmsghdr
   structure, and this is then used as the first argument to the next
   two functions.  Upon an error the return value is NULL.

8.3.  inet6_rthdr_add

    int inet6_rthdr_add(struct cmsghdr *cmsg,
                        const struct in6_addr *addr, unsigned int flags);

   This function adds the address pointed to by addr to the end of the
   Routing header being constructed and sets the type of this hop to the
   value of flags.  For an IPv6 Type 0 Routing header, flags must be

   If successful, the cmsg_len member of the cmsghdr structure is
   updated to account for the new address in the Routing header and the
   return value of the function is 0.  Upon an error the return value of
   the function is -1.

Top      Up      ToC       Page 46 
8.4.  inet6_rthdr_lasthop

       int inet6_rthdr_lasthop(struct cmsghdr *cmsg,
                               unsigned int flags);

   This function specifies the Strict/Loose flag for the final hop of a
   Routing header.  For an IPv6 Type 0 Routing header, flags must be

   The return value of the function is 0 upon success, or -1 upon an

   Notice that a Routing header specifying N intermediate nodes requires
   N+1 Strict/Loose flags.  This requires N calls to inet6_rthdr_add()
   followed by one call to inet6_rthdr_lasthop().

8.5.  inet6_rthdr_reverse

    int inet6_rthdr_reverse(const struct cmsghdr *in, struct cmsghdr *out);

   This function takes a Routing header that was received as ancillary
   data (pointed to by the first argument) and writes a new Routing
   header that sends datagrams along the reverse of that route.  Both
   arguments are allowed to point to the same buffer (that is, the
   reversal can occur in place).

   The return value of the function is 0 on success, or -1 upon an

8.6.  inet6_rthdr_segments

       int inet6_rthdr_segments(const struct cmsghdr *cmsg);

   This function returns the number of segments (addresses) contained in
   the Routing header described by cmsg.  On success the return value is
   between 1 and 23, inclusive.  The return value of the function is -1
   upon an error.

8.7.  inet6_rthdr_getaddr

    struct in6_addr *inet6_rthdr_getaddr(struct cmsghdr *cmsg, int

   This function returns a pointer to the IPv6 address specified by
   index (which must have a value between 1 and the value returned by
   inet6_rthdr_segments()) in the Routing header described by cmsg.  An
   application should first call inet6_rthdr_segments() to obtain the
   number of segments in the Routing header.

Top      Up      ToC       Page 47 
   Upon an error the return value of the function is NULL.

8.8.  inet6_rthdr_getflags

       int inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index);

   This function returns the flags value specified by index (which must
   have a value between 0 and the value returned by
   inet6_rthdr_segments()) in the Routing header described by cmsg.  For
   an IPv6 Type 0 Routing header the return value will be either

   Upon an error the return value of the function is -1.

   (Note: Addresses are indexed starting at 1, and flags starting at 0,
   to maintain consistency with the terminology and figures in [RFC-

8.9.  Routing Header Example

   As an example of these Routing header functions, we go through the
   function calls for the example on p. 18 of [RFC-1883].  The source is
   S, the destination is D, and the three intermediate nodes are I1, I2,
   and I3.  f0, f1, f2, and f3 are the Strict/Loose flags for each hop.

                   f0        f1        f2        f3
               S -----> I1 -----> I2 -----> I3 -----> D

       src:    *    S         S         S         S   S
       dst:    D   I1        I2        I3         D   D
       A[1]:  I1   I2        I1        I1        I1  I1
       A[2]:  I2   I3        I3        I2        I2  I2
       A[3]:  I3    D         D         D        I3  I3
       #seg:   3    3         2         1         0   3

       check: f0        f1        f2        f3

   src and dst are the source and destination IPv6 addresses in the IPv6
   header.  A[1], A[2], and A[3] are the three addresses in the Routing
   header.  #seg is the Segments Left field in the Routing header.
   check indicates which bit of the Strict/Loose Bit Map (0 through 3,
   specified as f0 through f3) that node checks.

   The six values in the column beneath node S are the values in the
   Routing header specified by the application using sendmsg().  The
   function calls by the sender would look like:

Top      Up      ToC       Page 48 
       void  *ptr;
       struct msghdr  msg;
       struct cmsghdr  *cmsgptr;
       struct sockaddr_in6  I1, I2, I3, D;
       unsigned int  f0, f1, f2, f3;

       ptr = malloc(inet6_rthdr_space(IPV6_RTHDR_TYPE_0, 3));
       cmsgptr = inet6_rthdr_init(ptr, IPV6_RTHDR_TYPE_0);

       inet6_rthdr_add(cmsgptr, &I1.sin6_addr, f0);
       inet6_rthdr_add(cmsgptr, &I2.sin6_addr, f1);
       inet6_rthdr_add(cmsgptr, &I3.sin6_addr, f2);
       inet6_rthdr_lasthop(cmsgptr, f3);

       msg.msg_control = ptr;
       msg.msg_controllen = cmsgptr->cmsg_len;

       /* finish filling in msg{}, msg_name = D */
       /* call sendmsg() */

   We also assume that the source address for the socket is not
   specified (i.e., the asterisk in the figure).

   The four columns of six values that are then shown between the five
   nodes are the values of the fields in the packet while the packet is
   in transit between the two nodes.  Notice that before the packet is
   sent by the source node S, the source address is chosen (replacing
   the asterisk), I1 becomes the destination address of the datagram,
   the two addresses A[2] and A[3] are "shifted up", and D is moved to
   A[3].  If f0 is IPV6_RTHDR_STRICT, then I1 must be a neighbor of S.

   The columns of values that are shown beneath the destination node are
   the values returned by recvmsg(), assuming the application has
   enabled both the IPV6_PKTINFO and IPV6_RTHDR socket options.  The
   source address is S (contained in the sockaddr_in6 structure pointed
   to by the msg_name member), the destination address is D (returned as
   an ancillary data object in an in6_pktinfo structure), and the
   ancillary data object specifying the Routing header will contain
   three addresses (I1, I2, and I3) and four flags (f0, f1, f2, and f3).
   The number of segments in the Routing header is known from the Hdr
   Ext Len field in the Routing header (a value of 6, indicating 3

   The return value from inet6_rthdr_segments() will be 3 and
   inet6_rthdr_getaddr(1) will return I1, inet6_rthdr_getaddr(2) will
   return I2, and inet6_rthdr_getaddr(3) will return I3, The return

Top      Up      ToC       Page 49 
   value from inet6_rthdr_flags(0) will be f0, inet6_rthdr_flags(1) will
   return f1, inet6_rthdr_flags(2) will return f2, and
   inet6_rthdr_flags(3) will return f3.

   If the receiving application then calls inet6_rthdr_reverse(), the
   order of the three addresses will become I3, I2, and I1, and the
   order of the four Strict/Loose flags will become f3, f2, f1, and f0.

   We can also show what an implementation might store in the ancillary
   data object as the Routing header is being built by the sending
   process.  If we assume a 32-bit architecture where sizeof(struct
   cmsghdr) equals 12, with a desired alignment of 4-byte boundaries,
   then the call to inet6_rthdr_space(3) returns 68: 12 bytes for the
   cmsghdr structure and 56 bytes for the Routing header (8 + 3*16).

   The call to inet6_rthdr_init() initializes the ancillary data object
   to contain a Type 0 Routing header:

     |       cmsg_len = 20                                           |
     |       cmsg_level = IPPROTO_IPV6                               |
     |       cmsg_type = IPV6_RTHDR                                  |
     |  Next Header  | Hdr Ext Len=0 | Routing Type=0|  Seg Left=0   |
     |   Reserved    |             Strict/Loose Bit Map              |

   The first call to inet6_rthdr_add() adds I1 to the list.

Top      Up      ToC       Page 50 
     |       cmsg_len = 36                                           |
     |       cmsg_level = IPPROTO_IPV6                               |
     |       cmsg_type = IPV6_RTHDR                                  |
     |  Next Header  | Hdr Ext Len=2 | Routing Type=0|  Seg Left=1   |
     |   Reserved    |X|           Strict/Loose Bit Map              |
     |                                                               |
     +                                                               +
     |                                                               |
     +                           Address[1] = I1                     +
     |                                                               |
     +                                                               +
     |                                                               |

   Bit 0 of the Strict/Loose Bit Map contains the value f0, which we
   just mark as X.  cmsg_len is incremented by 16, the Hdr Ext Len field
   is incremented by 2, and the Segments Left field is incremented by 1.

   The next call to inet6_rthdr_add() adds I2 to the list.

Top      Up      ToC       Page 51 
     |       cmsg_len = 52                                           |
     |       cmsg_level = IPPROTO_IPV6                               |
     |       cmsg_type = IPV6_RTHDR                                  |
     |  Next Header  | Hdr Ext Len=4 | Routing Type=0|  Seg Left=2   |
     |   Reserved    |X|X|         Strict/Loose Bit Map              |
     |                                                               |
     +                                                               +
     |                                                               |
     +                           Address[1] = I1                     +
     |                                                               |
     +                                                               +
     |                                                               |
     |                                                               |
     +                                                               +
     |                                                               |
     +                           Address[2] = I2                     +
     |                                                               |
     +                                                               +
     |                                                               |

   The next bit of the Strict/Loose Bit Map contains the value f1.
   cmsg_len is incremented by 16, the Hdr Ext Len field is incremented
   by 2, and the Segments Left field is incremented by 1.

   The last call to inet6_rthdr_add() adds I3 to the list.

Top      Up      ToC       Page 52 
     |       cmsg_len = 68                                           |
     |       cmsg_level = IPPROTO_IPV6                               |
     |       cmsg_type = IPV6_RTHDR                                  |
     |  Next Header  | Hdr Ext Len=6 | Routing Type=0|  Seg Left=3   |
     |   Reserved    |X|X|X|       Strict/Loose Bit Map              |
     |                                                               |
     +                                                               +
     |                                                               |
     +                           Address[1] = I1                     +
     |                                                               |
     +                                                               +
     |                                                               |
     |                                                               |
     +                                                               +
     |                                                               |
     +                           Address[2] = I2                     +
     |                                                               |
     +                                                               +
     |                                                               |
     |                                                               |
     +                                                               +
     |                                                               |
     +                           Address[3] = I3                     +
     |                                                               |
     +                                                               +
     |                                                               |

   The next bit of the Strict/Loose Bit Map contains the value f2.
   cmsg_len is incremented by 16, the Hdr Ext Len field is incremented
   by 2, and the Segments Left field is incremented by 1.

   Finally, the call to inet6_rthdr_lasthop() sets the next bit of the
   Strict/Loose Bit Map to the value specified by f3.  All the lengths
   remain unchanged.

Top      Up      ToC       Page 53 
9.  Ordering of Ancillary Data and IPv6 Extension Headers

   Three IPv6 extension headers can be specified by the application and
   returned to the application using ancillary data with sendmsg() and
   recvmsg(): Hop-by-Hop options, Destination options, and the Routing
   header.  When multiple ancillary data objects are transferred via
   sendmsg() or recvmsg() and these objects represent any of these three
   extension headers, their placement in the control buffer is directly
   tied to their location in the corresponding IPv6 datagram.  This API
   imposes some ordering constraints when using multiple ancillary data
   objects with sendmsg().

   When multiple IPv6 Hop-by-Hop options having the same option type are
   specified, these options will be inserted into the Hop-by-Hop options
   header in the same order as they appear in the control buffer.  But
   when multiple Hop-by-Hop options having different option types are
   specified, these options may be reordered by the kernel to reduce
   padding in the Hop-by-Hop options header.  Hop-by-Hop options may
   appear anywhere in the control buffer and will always be collected by
   the kernel and placed into a single Hop-by-Hop options header that
   immediately follows the IPv6 header.

   Similar rules apply to the Destination options: (1) those of the same
   type will appear in the same order as they are specified, and (2)
   those of differing types may be reordered.  But the kernel will build
   up to two Destination options headers: one to precede the Routing
   header and one to follow the Routing header.  If the application
   specifies a Routing header then all Destination options that appear
   in the control buffer before the Routing header will appear in a
   Destination options header before the Routing header and these
   options might be reordered, subject to the two rules that we just
   stated.  Similarly all Destination options that appear in the control
   buffer after the Routing header will appear in a Destination options
   header after the Routing header, and these options might be
   reordered, subject to the two rules that we just stated.

   As an example, assume that an application specifies control
   information to sendmsg() containing six ancillary data objects: the
   first containing two Hop-by-Hop options, the second containing one
   Destination option, the third containing two Destination options, the
   fourth containing a Routing header, the fifth containing a Hop-by-Hop
   option, and the sixth containing two Destination options.  We also
   assume that all the Hop-by-Hop options are of different types, as are
   all the Destination options.  We number these options 1-9,
   corresponding to their order in the control buffer, and show them on
   the left below.

Top      Up      ToC       Page 54 
   In the middle we show the final arrangement of the options in the
   extension headers built by the kernel.  On the right we show the four
   ancillary data objects returned to the receiving application.

          Sender's                                       Receiver's
       Ancillary Data      -->   IPv6 Extension   -->  Ancillary Data
          Objects                    Headers              Objects
       ------------------        ---------------       --------------
       HOPOPT-1,2 (first)        HOPHDR(J,7,1,2)       HOPOPT-7,1,2
       DSTOPT-3                  DSTHDR(4,5,3)         DSTOPT-4,5,3
       DSTOPT-4,5                RTHDR(6)              RTHDR-6
       RTHDR-6                   DSTHDR(8,9)           DSTOPT-8,9
       DSTOPT-8,9 (last)

   The sender's two Hop-by-Hop ancillary data objects are reordered, as
   are the first two Destination ancillary data objects.  We also show a
   Jumbo Payload option (denoted as J) inserted by the kernel before the
   sender's three Hop-by-Hop options.  The first three Destination
   options must appear in a Destination header before the Routing
   header, and the final two Destination options must appear in a
   Destination header after the Routing header.

   If Destination options are specified in the control buffer after a
   Routing header, or if Destination options are specified without a
   Routing header, the kernel will place those Destination options after
   an authentication header and/or an encapsulating security payload
   header, if present.

10.  IPv6-Specific Options with IPv4-Mapped IPv6 Addresses

   The various socket options and ancillary data specifications defined
   in this document apply only to true IPv6 sockets.  It is possible to
   create an IPv6 socket that actually sends and receives IPv4 packets,
   using IPv4-mapped IPv6 addresses, but the mapping of the options
   defined in this document to an IPv4 datagram is beyond the scope of
   this document.

   In general, attempting to specify an IPv6-only option, such as the
   Hop-by-Hop options, Destination options, or Routing header on an IPv6
   socket that is using IPv4-mapped IPv6 addresses, will probably result
   in an error.  Some implementations, however, may provide access to
   the packet information (source/destination address, send/receive
   interface, and hop limit) on an IPv6 socket that is using IPv4-mapped
   IPv6 addresses.

Top      Up      ToC       Page 55 
11.  rresvport_af

   The rresvport() function is used by the rcmd() function, and this
   function is in turn called by many of the "r" commands such as
   rlogin.  While new applications are not being written to use the
   rcmd() function, legacy applications such as rlogin will continue to
   use it and these will be ported to IPv6.

   rresvport() creates an IPv4/TCP socket and binds a "reserved port" to
   the socket.  Instead of defining an IPv6 version of this function we
   define a new function that takes an address family as its argument.

       #include <unistd.h>

       int  rresvport_af(int *port, int family);

   This function behaves the same as the existing rresvport() function,
   but instead of creating an IPv4/TCP socket, it can also create an
   IPv6/TCP socket.  The family argument is either AF_INET or AF_INET6,
   and a new error return is EAFNOSUPPORT if the address family is not

   (Note: There is little consensus on which header defines the
   rresvport() and rcmd() function prototypes.  4.4BSD defines it in
   <unistd.h>, others in <netdb.h>, and others don't define the function
   prototypes at all.)

   (Note: We define this function only, and do not define something like
   rcmd_af() or rcmd6().  The reason is that rcmd() calls
   gethostbyname(), which returns the type of address: AF_INET or
   AF_INET6.  It should therefore be possible to modify rcmd() to
   support either IPv4 or IPv6, based on the address family returned by

12.  Future Items

   Some additional items may require standardization, but no concrete
   proposals have been made for the API to perform these tasks.  These
   may be addressed in a later document.

12.1.  Flow Labels

   Earlier revisions of this document specified a set of
   inet6_flow_XXX() functions to assign, share, and free IPv6 flow
   labels.  Consensus, however, indicated that it was premature to
   specify this part of the API.

Top      Up      ToC       Page 56 
12.2.  Path MTU Discovery and UDP

   A standard method may be desirable for a UDP application to determine
   the "maximum send transport-message size" (Section 5.1 of [RFC-1981])
   to a given destination.  This would let the UDP application send
   smaller datagrams to the destination, avoiding fragmentation.

12.3.  Neighbor Reachability and UDP

   A standard method may be desirable for a UDP application to tell the
   kernel that it is making forward progress with a given peer (Section
   7.3.1 of [RFC-1970]).  This could save unneeded neighbor
   solicitations and neighbor advertisements.

13.  Summary of New Definitions

   The following list summarizes the constants and structure,
   definitions discussed in this memo, sorted by header.

     <netinet/icmp6.h> ICMP6_DST_UNREACH
     <netinet/icmp6.h> ICMP6_DST_UNREACH_ADDR
     <netinet/icmp6.h> ICMP6_DST_UNREACH_ADMIN
     <netinet/icmp6.h> ICMP6_DST_UNREACH_NOPORT
     <netinet/icmp6.h> ICMP6_DST_UNREACH_NOROUTE
     <netinet/icmp6.h> ICMP6_DST_UNREACH_NOTNEIGHBOR
     <netinet/icmp6.h> ICMP6_ECHO_REPLY
     <netinet/icmp6.h> ICMP6_ECHO_REQUEST
     <netinet/icmp6.h> ICMP6_INFOMSG_MASK
     <netinet/icmp6.h> ICMP6_MEMBERSHIP_QUERY
     <netinet/icmp6.h> ICMP6_MEMBERSHIP_REDUCTION
     <netinet/icmp6.h> ICMP6_MEMBERSHIP_REPORT
     <netinet/icmp6.h> ICMP6_PACKET_TOO_BIG
     <netinet/icmp6.h> ICMP6_PARAMPROB_HEADER
     <netinet/icmp6.h> ICMP6_PARAMPROB_NEXTHEADER
     <netinet/icmp6.h> ICMP6_PARAMPROB_OPTION
     <netinet/icmp6.h> ICMP6_PARAM_PROB
     <netinet/icmp6.h> ICMP6_TIME_EXCEEDED
     <netinet/icmp6.h> ICMP6_TIME_EXCEED_REASSEMBLY
     <netinet/icmp6.h> ICMP6_TIME_EXCEED_TRANSIT
     <netinet/icmp6.h> ND_NA_FLAG_OVERRIDE
     <netinet/icmp6.h> ND_NA_FLAG_ROUTER
     <netinet/icmp6.h> ND_NA_FLAG_SOLICITED
     <netinet/icmp6.h> ND_NEIGHBOR_ADVERT
     <netinet/icmp6.h> ND_NEIGHBOR_SOLICIT
     <netinet/icmp6.h> ND_OPT_MTU
     <netinet/icmp6.h> ND_OPT_PI_FLAG_AUTO
     <netinet/icmp6.h> ND_OPT_PI_FLAG_ONLINK
     <netinet/icmp6.h> ND_OPT_PREFIX_INFORMATION

Top      Up      ToC       Page 57 
     <netinet/icmp6.h> ND_OPT_REDIRECTED_HEADER
     <netinet/icmp6.h> ND_OPT_SOURCE_LINKADDR
     <netinet/icmp6.h> ND_OPT_TARGET_LINKADDR
     <netinet/icmp6.h> ND_RA_FLAG_MANAGED
     <netinet/icmp6.h> ND_RA_FLAG_OTHER
     <netinet/icmp6.h> ND_REDIRECT
     <netinet/icmp6.h> ND_ROUTER_ADVERT
     <netinet/icmp6.h> ND_ROUTER_SOLICIT

     <netinet/icmp6.h> struct icmp6_filter{};
     <netinet/icmp6.h> struct icmp6_hdr{};
     <netinet/icmp6.h> struct nd_neighbor_advert{};
     <netinet/icmp6.h> struct nd_neighbor_solicit{};
     <netinet/icmp6.h> struct nd_opt_hdr{};
     <netinet/icmp6.h> struct nd_opt_mtu{};
     <netinet/icmp6.h> struct nd_opt_prefix_info{};
     <netinet/icmp6.h> struct nd_opt_rd_hdr{};
     <netinet/icmp6.h> struct nd_redirect{};
     <netinet/icmp6.h> struct nd_router_advert{};
     <netinet/icmp6.h> struct nd_router_solicit{};

     <netinet/in.h>    IPPROTO_AH
     <netinet/in.h>    IPPROTO_DSTOPTS
     <netinet/in.h>    IPPROTO_ESP
     <netinet/in.h>    IPPROTO_FRAGMENT
     <netinet/in.h>    IPPROTO_HOPOPTS
     <netinet/in.h>    IPPROTO_ICMPV6
     <netinet/in.h>    IPPROTO_IPV6
     <netinet/in.h>    IPPROTO_NONE
     <netinet/in.h>    IPPROTO_ROUTING
     <netinet/in.h>    IPV6_DSTOPTS
     <netinet/in.h>    IPV6_HOPLIMIT
     <netinet/in.h>    IPV6_HOPOPTS
     <netinet/in.h>    IPV6_NEXTHOP
     <netinet/in.h>    IPV6_PKTINFO
     <netinet/in.h>    IPV6_PKTOPTIONS
     <netinet/in.h>    IPV6_RTHDR
     <netinet/in.h>    IPV6_RTHDR_LOOSE
     <netinet/in.h>    IPV6_RTHDR_STRICT
     <netinet/in.h>    IPV6_RTHDR_TYPE_0
     <netinet/in.h>    struct in6_pktinfo{};

     <netinet/ip6.h>   IP6F_OFF_MASK
     <netinet/ip6.h>   IP6F_RESERVED_MASK
     <netinet/ip6.h>   IP6F_MORE_FRAG
     <netinet/ip6.h>   struct ip6_dest{};
     <netinet/ip6.h>   struct ip6_frag{};
     <netinet/ip6.h>   struct ip6_hbh{};

Top      Up      ToC       Page 58 
     <netinet/ip6.h>   struct ip6_hdr{};
     <netinet/ip6.h>   struct ip6_rthdr{};
     <netinet/ip6.h>   struct ip6_rthdr0{};

     <sys/socket.h>    struct cmsghdr{};
     <sys/socket.h>    struct msghdr{};

   The following list summarizes the function and macro prototypes
   discussed in this memo, sorted by header.

<netinet/icmp6.h> void ICMP6_FILTER_SETBLOCK(int,
                                                struct icmp6_filter *);
<netinet/icmp6.h> void ICMP6_FILTER_SETBLOCKALL(struct icmp6_filter *);
<netinet/icmp6.h> void ICMP6_FILTER_SETPASS(int, struct icmp6_filter *);
<netinet/icmp6.h> void ICMP6_FILTER_SETPASSALL(struct icmp6_filter *);
<netinet/icmp6.h> int  ICMP6_FILTER_WILLBLOCK(int,
                                           const struct icmp6_filter *);
<netinet/icmp6.h> int  ICMP6_FILTER_WILLPASS(int,
                                           const struct icmp6_filter *);

<netinet/in.h>    int IN6_ARE_ADDR_EQUAL(const struct in6_addr *,
                                         const struct in6_addr *);

<netinet/in.h>    uint8_t *inet6_option_alloc(struct cmsghdr *,
                                               int, int, int);
<netinet/in.h>    int inet6_option_append(struct cmsghdr *,
                                          const uint8_t *, int, int);
<netinet/in.h>    int inet6_option_find(const struct cmsghdr *,
                                        uint8_t *, int);
<netinet/in.h>    int inet6_option_init(void *, struct cmsghdr **, int);
<netinet/in.h>    int inet6_option_next(const struct cmsghdr *,
                                        uint8_t **);
<netinet/in.h>    int inet6_option_space(int);

<netinet/in.h>    int inet6_rthdr_add(struct cmsghdr *,
                                      const struct in6_addr *,
                                      unsigned int);
<netinet/in.h>    struct in6_addr inet6_rthdr_getaddr(struct cmsghdr *,
<netinet/in.h>    int inet6_rthdr_getflags(const struct cmsghdr *, int);
<netinet/in.h>    struct cmsghdr *inet6_rthdr_init(void *, int);
<netinet/in.h>    int inet6_rthdr_lasthop(struct cmsghdr *,
                                                          unsigned int);
<netinet/in.h>    int inet6_rthdr_reverse(const struct cmsghdr *,
                                          struct cmsghdr *);
<netinet/in.h>    int inet6_rthdr_segments(const struct cmsghdr *);
<netinet/in.h>    size_t inet6_rthdr_space(int, int);

Top      Up      ToC       Page 59 
<sys/socket.h>    unsigned char *CMSG_DATA(const struct cmsghdr *);
<sys/socket.h>    struct cmsghdr *CMSG_FIRSTHDR(const struct msghdr *);
<sys/socket.h>    unsigned int CMSG_LEN(unsigned int);
<sys/socket.h>    struct cmsghdr *CMSG_NXTHDR(const struct msghdr *mhdr,
                                              const struct cmsghdr *);
<sys/socket.h>    unsigned int CMSG_SPACE(unsigned int);

<unistd.h>        int rresvport_af(int *, int);

14.  Security Considerations

   The setting of certain Hop-by-Hop options and Destination options may
   be restricted to privileged processes.  Similarly some Hop-by-Hop
   options and Destination options may not be returned to nonprivileged

15.  Change History

   Changes from the June 1997 Edition (-03 draft)

    -  Added a note that defined constants for multibyte fields are in
       network byte order.  This affects the ip6f_offlg member of the
       Fragment header (Section 2.1.2) and the nd_na_flags_reserved
       member of the nd_neighbor_advert structure (Section 2.2.2).

    -  Section 5: the ipi6_ifindex member of the in6_pktinfo structure
       should be "unsigned int" instead of "int", for consistency with
       the interface indexes in [RFC-2133].

    -  Section 6.3.7: the three calls to inet6_option_space() in the
       examples needed to be arguments to malloc().  The final one of
       these was missing the "6" in the name "inet6_option_space".

    -  Section 8.6: the function prototype for inet6_rthdr_segments()
       was missing the ending semicolon.

   Changes from the March 1997 Edition (-02 draft)

    -  In May 1997 Draft 6.6 of Posix 1003.1g (called Posix.1g herein)
       passed ballot and will be forwarded to the IEEE Standards Board
       later in 1997 for final approval.  Some changes made for this
       final Posix draft are incorporated into this Internet Draft,
       specifically the datatypes mentioned in Section 1 (and used
       throughout the text), and the socklen_t datatype used in Section
       4.1 and 4.2.

    -  Section 1: Added the intN_t signed datatypes, changed the
       datatype u_intN_t to uintN_t (no underscore after the "u"), and

Top      Up      ToC       Page 60 
       removed the datatype u_intNm_t, as per Draft 6.6 of Posix.1g.

    -  Name space issues for structure and constant names in Section 2:
       Many of the structure member names and constant names were
       changed so that the prefixes are the same.  The following
       prefixes are used for structure members: "ip6_", "icmp6_", and
       "nd_".  All constants have the prefixes "ICMP6_" and "ND_".

    -  New definitions: Section 2.1.2: contains definitions for the IPv6
       extension headers, other than AH and ESP.  Section 2.2.2:
       contains additional structures and constants for the neighbor
       discovery option header and redirected header.

    -  Section 2.2.2: the enum for the neighbor discovery option field
       was changed to be a set of #define constants.

    -  Changed the word "function" to "macro" for references to all the
       uppercase names in Sections 2.3 (IN6_ARE_ADDR_EQUAL), 3.2
       (ICMPV6_FILTER_xxx), and 4.3 (CMSG_xxx).

    -  Added more protocols to the /etc/protocols file (Section 2.4) and
       changed the name of "icmpv6" to "ipv6-icmp".

    -  Section 3: Made it more explicit that an application cannot read
       or write entire IPv6 packets, that all extension headers are
       passed as ancillary data.  Added a sentence that the kernel
       fragments packets written to an IPv6 raw socket when necessary.
       Added a note that IPPROTO_RAW raw IPv6 sockets are not special.

    -  Section 3.1: Explicitly stated that the checksum option applies
       to both outgoing packets and received packets.

    -  Section 3.2: Changed the array name within the icmp6_filter
       structure from "data" to "icmp6_filt".  Changes the prefix for
       the filter macros from "ICMPV6_" to "ICMP6_", for consistency
       with the names in Section 2.2.  Changed the example from a ping
       program to a program that wants to receive only router

    -  Section 4.1: Changed msg_namelen and msg_controllen from size_t
       to the Posix.1g socklen_t datatype.  Updated the Note that

    -  Section 4.2: Changed cmsg_len from size_t to the Posix.1g
       socklen_t datatype.  Updated the Note that follows.

Top      Up      ToC       Page 61 
    -  Section 4.4: Added a Note that the second and third arguments to
       getsockopt() and setsockopt() are intentionally the same as the
       cmsg_level and cmsg_type members.

    -  Section 4.5: Reorganized the section into a description of the
       option, followed by the TCP semantics, and the UDP and raw socket
       semantics.  Added a sentence on how to clear all the sticky
       options.  Added a note that TCP need not save the options from
       the most recently received segment until the application says to
       do so.  Added the statement that ancillary data is never passed
       with sendmsg() or recvmsg() on a TCP socket.  Simplified the
       interaction of the sticky options with ancillary data for UDP or
       raw IP: none of the sticky options are sent if ancillary data is

    -  Final paragraph of Section 5.1: ipi6_index should be

    -  Section 5.4: Added a note on the term "privileged".

    -  Section 5.5: Noted that the errors listed are examples, and the
       actual errors depend on the implementation.

    -  Removed Section 6 ("Flow Labels") as the consensus is that it is
       premature to try and specify an API for this feature.  Access to
       the flow label field in the IPv6 header is still provided through
       the sin6_flowinfo member of the IPv6 socket address structure in
       [RFC-2133].  Added a subsection to Section 13 that this is a
       future item.

       All remaining changes are identified by their section number in
       the previous draft.  With the removal of Section 6, the section
       numbers are decremented by one.

    -  Section 7.3.7: the calls to malloc() in all three examples should
       be calls to inet6_option_space() instead.  The two calls to
       inet6_option_append() in the third example should be calls to
       inet6_option_alloc().  The two calls to CMSG_SPACE() in the first
       and third examples should be calls to CMSG_LEN().  The second
       call to CMSG_SPACE() in the second example should be a call to

    -  Section 7.3.7: All the opt_X_ and opt_Y_ structure member names
       were changed to be ip6_X_opt_ and ip6_Y_opt_.  The two structure
       names ipv6_opt_X and ipv6_opt_Y were changed to ip6_X_opt and
       ip6_Y_opt.  The constants beginning with IPV6_OPT_X_ and
       IPV6_OPT_Y_ were changed to begin with IP6_X_OPT_ and IP6_Y_OPT_.

Top      Up      ToC       Page 62 
    -  Use the term "Routing header" throughout the draft, instead of
       "source routing".  Changed the names of the eight
       inet6_srcrt_XXX() functions in Section 9 to inet6_rthdr_XXX().
       Changed the name of the socket option from IPV6_SRCRT to
       IPV6_RTHDR, and the names of the three IPV6_SRCRT_xxx constants
       in Section 9 to IPV6_RTHDR_xxx.

    -  Added a paragraph to Section 9 on how to receive and send a
       Routing header.

    -  Changed inet6_rthdr_add() and inet6_rthdr_reverse() so that they
       return -1 upon an error, instead of an Exxx errno value.

    -  In the description of inet6_rthdr_space() in Section 9.1, added
       the qualifier "For an IPv6 Type 0 Routing header" to the
       restriction of between 1 and 23 segments.

    -  Refer to final function argument in Sections 9.7 and 9.8 as
       index, not offset.

    -  Updated Section 14 with new names from Section 2.

    -  Changed the References from "[n]" to "[RFC-abcd]".

   Changes from the February 1997 Edition (-01 draft)

    -  Changed the name of the ip6hdr structure to ip6_hdr (Section 2.1)
       for consistency with the icmp6hdr structure.  Also changed the
       name of the ip6hdrctl structure contained within the ip6_hdr
       structure to ip6_hdrctl (Section 2.1).  Finally, changed the name
       of the icmp6hdr structure to icmp6_hdr (Section 2.2).  All other
       occurrences of this structure name, within the Neighbor Discovery
       structures in Section 2.2.1, already contained the underscore.

    -  The "struct nd_router_solicit" and "struct nd_router_advert"
       should both begin with "nd6_". (Section 2.2.2).

    -  Changed the name of in6_are_addr_equal to IN6_ARE_ADDR_EQUAL
       (Section 2.3) for consistency with basic API address testing
       functions.  The header defining this macro is <netinet/in.h>.

    -  getprotobyname("ipv6") now returns 41, not 0 (Section 2.4).

    -  The first occurrence of "struct icmpv6_filter" in Section 3.2
       should be "struct icmp6_filter".

    -  Changed the name of the CMSG_LENGTH() macro to CMSG_LEN()
       (Section 4.3.5), since LEN is used throughout the <netinet/*.h>

Top      Up      ToC       Page 63 

    -  Corrected the argument name for the sample implementations of the
       CMSG_SPACE() and CMSG_LEN() macros to be "length" (Sections 4.3.4
       and 4.3.5).

    -  Corrected the socket option mentioned in Section 5.1 to specify
       the interface for multicasting from IPV6_ADD_MEMBERSHIP to

    -  There were numerous errors in the previous draft that specified
       <netinet/ip6.h> that should have been <netinet/in.h>.  These have
       all been corrected and the locations of all definitions is now
       summarized in the new Section 14 ("Summary of New Definitions").

    Changes from the October 1996 Edition (-00 draft)

    -  Numerous rationale added using the format (Note: ...).

    -  Added note that not all errors may be defined.

    -  Added note about ICMPv4, IGMPv4, and ARPv4 terminology.

    -  Changed the name of <netinet/ip6_icmp.h> to <netinet/icmp6.h>.

    -  Changed some names in Section 2.2.1: ICMPV6_PKT_TOOBIG to

    -  Prepend the prefix "icmp6_" to the three members of the
       icmp6_dataun union of the icmp6hdr structure (Section 2.2).

    -  Moved the neighbor discovery definitions into the
       <netinet/icmp6.h> header, instead of being in their own header
       (Section 2.2.1).

    -  Changed Section 2.3 ("Address Testing").  The basic macros are
       now in the basic API.

    -  Added the new Section 2.4 on "Protocols File".

    -  Added note to raw sockets description that something like BPF or
       DLPI must be used to read or write entire IPv6 packets.

Top      Up      ToC       Page 64 
    -  Corrected example of IPV6_CHECKSUM socket option (Section 3.1).
       Also defined value of -1 to disable.

    -  Noted that <netinet/icmp6.h> defines all the ICMPv6 filtering
       constants, macros, and structures (Section 3.2).

    -  Added note on magic number 10240 for amount of ancillary data
       (Section 4.1).

    -  Added possible padding to picture of ancillary data (Section

    -  Defined <sys/socket.h> header for CMSG_xxx() functions (Section

    -  Note that the data returned by getsockopt(IPV6_PKTOPTIONS) for a
       TCP socket is just from the optional headers, if present, of the
       most recently received segment.  Also note that control
       information is never returned by recvmsg() for a TCP socket.

    -  Changed header for struct in6_pktinfo from <> to
       <netinet/ip6.h> (Section 5).

    -  Removed the old Sections 5.1 and 5.2, because the interface
       identification functions went into the basic API.

    -  Redid Section 5 to support the hop limit field.

    -  New Section 5.4 ("Next Hop Address").

    -  New Section 6 ("Flow Labels").

    -  Changed all of Sections 7 and 8 dealing with Hop-by-Hop and
       Destination options.  We now define a set of inet6_option_XXX()

    -  Changed header for IPV6_SRCRT_xxx constants from <>
       to <netinet/ip6.h> (Section 9).

    -  Add inet6_rthdr_lasthop() function, and fix errors in description
       of Routing header (Section 9).

    -  Reworded some of the Routing header descriptions to conform to
       the terminology in [RFC-1883].

    -  Added the example from [RFC-1883] for the Routing header (Section

Top      Up      ToC       Page 65 
    -  Expanded the example in Section 10 to show multiple options per
       ancillary data object, and to show the receiver's ancillary data

    -  New Section 11 ("IPv6-Specific Options with IPv4-Mapped IPv6

    -  New Section 12 ("rresvport_af").

    -  Redid old Section 10 ("Additional Items") into new Section 13
       ("Future Items").

16.  References

   [RFC-1883]  Deering, S., and R. Hinden, "Internet Protocol, Version 6
               (IPv6), Specification", RFC 1883, December 1995.

   [RFC-2133]  Gilligan, R., Thomson, S., Bound, J., and W. Stevens,
               "Basic Socket Interface Extensions for IPv6", RFC 2133,
               April 1997.

   [RFC-1981]  McCann, J., Deering, S., and J. Mogul, "Path MTU
               for IP version 6", RFC 1981, August 1996.

   [RFC-1970]  Narten, T., Nordmark, E., and W. Simpson, "Neighbor
               Discovery for IP Version 6 (IPv6)", RFC 1970, August

17.  Acknowledgments

   Matt Thomas and Jim Bound have been working on the technical details
   in this draft for over a year.  Keith Sklower is the original
   implementor of ancillary data in the BSD networking code.  Craig Metz
   provided lots of feedback, suggestions, and comments based on his
   implementing many of these features as the document was being

   The following provided comments on earlier drafts: Pascal Anelli,
   Hamid Asayesh, Ran Atkinson, Karl Auerbach, Hamid Asayesh, Matt
   Crawford, Sam T. Denton, Richard Draves, Francis Dupont, Bob
   Gilligan, Tim Hartrick, Masaki Hirabaru, Yoshinobu Inoue, Mukesh
   Kacker, A. N. Kuznetsov, Pedro Marques, Jack McCann, der Mouse, John
   Moy, Thomas Narten, Erik Nordmark, Steve Parker, Charles Perkins, Tom
   Pusateri, Pedro Roque, Sameer Shah, Peter Sjodin, Stephen P.
   Spackman, Jinmei Tatuya, Karen Tracey, Quaizar Vohra, Carl Williams,
   Steve Wise, and Kazu Yamamoto.

Top      Up      ToC       Page 66 
18.  Authors' Addresses

   W. Richard Stevens
   1202 E. Paseo del Zorro
   Tucson, AZ  85718


   Matt Thomas
   AltaVista Internet Software
   30 Porter Rd
   Littleton, MA  01460

Top      Up      ToC       Page 67 
19.  Full Copyright Statement

   Copyright (C) The Internet Society (1998).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an