1.\" Copyright (c) 1983, 1987, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" $Id: inet6_rthdr_space.3,v 1.5 2000/02/05 13:19:07 jinmei Exp $ 33.\" $FreeBSD$ 34.\" 35.Dd December 10, 1999 36.Dt INET6_RTHDR_SPACE 3 37.Os 38.\" 39.Sh NAME 40.Nm inet6_rthdr_space , 41.Nm inet6_rthdr_init , 42.Nm inet6_rthdr_add , 43.Nm inet6_rthdr_lasthop , 44.Nm inet6_rthdr_reverse , 45.Nm inet6_rthdr_segments , 46.Nm inet6_rthdr_getaddr , 47.Nm inet6_rthdr_getflags 48.Nd IPv6 Routing Header Options manipulation 49.\" 50.Sh LIBRARY 51.Lb libc 52.Sh SYNOPSIS 53.In sys/types.h 54.In netinet/in.h 55.Ft size_t 56.Fn inet6_rthdr_space "int type" "int segments" 57.Ft "struct cmsghdr *" 58.Fn inet6_rthdr_init "void *bp" "int type" 59.Ft int 60.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags" 61.Ft int 62.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags" 63.Ft int 64.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out" 65.Ft int 66.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg" 67.Ft "struct in6_addr *" 68.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index" 69.Ft int 70.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index" 71.\" 72.Sh DESCRIPTION 73RFC2292 IPv6 advanced API defines eight 74functions that the application calls to build and examine a Routing 75header. Four functions build a Routing header: 76.Bl -hang 77.It Fn inet6_rthdr_space 78return #bytes required for ancillary data 79.It Fn inet6_rthdr_init 80initialize ancillary data for Routing header 81.It Fn inet6_rthdr_add 82add IPv6 address & flags to Routing header 83.It Fn inet6_rthdr_lasthop 84specify the flags for the final hop 85.El 86.Pp 87Four functions deal with a returned Routing header: 88.Bl -hang 89.It Fn inet6_rthdr_reverse 90reverse a Routing header 91.It Fn inet6_rthdr_segments 92return #segments in a Routing header 93.It Fn inet6_rthdr_getaddr 94fetch one address from a Routing header 95.It Fn inet6_rthdr_getflags 96fetch one flag from a Routing header 97.El 98.Pp 99The function prototypes for these functions are all in the 100.Aq Li netinet/in.h 101header. 102.\" 103.Ss inet6_rthdr_space 104This function returns the number of bytes required to hold a Routing 105header of the specified 106.Fa type 107containing the specified number of 108.Fa segments 109(addresses). 110For an IPv6 Type 0 Routing header, the number 111of segments must be between 1 and 23, inclusive. The return value 112includes the size of the cmsghdr structure that precedes the Routing 113header, and any required padding. 114.Pp 115If the return value is 0, then either the type of the Routing header 116is not supported by this implementation or the number of segments is 117invalid for this type of Routing header. 118.Pp 119Note: This function returns the size but does not allocate the space 120required for the ancillary data. 121This allows an application to 122allocate a larger buffer, if other ancillary data objects are 123desired, since all the ancillary data objects must be specified to 124.Xr sendmsg 2 125as a single 126.Li msg_control 127buffer. 128.\" 129.Ss inet6_rthdr_init 130This function initializes the buffer pointed to by 131.Fa bp 132to contain a 133.Li cmsghdr 134structure followed by a Routing header of the specified 135.Fa type . 136The 137.Li cmsg_len 138member of the 139.Li cmsghdr 140structure is initialized to the 141size of the structure plus the amount of space required by the 142Routing header. 143The 144.Li cmsg_level 145and 146.Li cmsg_type 147members are also initialized as required. 148.Pp 149The caller must allocate the buffer and its size can be determined by 150calling 151.Fn inet6_rthdr_space . 152.Pp 153Upon success the return value is the pointer to the 154.Li cmsghdr 155structure, and this is then used as the first argument to the next 156two functions. 157Upon an error the return value is 158.Dv NULL . 159.\" 160.Ss inet6_rthdr_add 161This function adds the address pointed to by 162.Fa addr 163to the end of the 164Routing header being constructed and sets the type of this hop to the 165value of 166.Fa flags . 167For an IPv6 Type 0 Routing header, 168.Fa flags 169must be 170either 171.Dv IPV6_RTHDR_LOOSE 172or 173.Dv IPV6_RTHDR_STRICT . 174.Pp 175If successful, the 176.Li cmsg_len 177member of the 178.Li cmsghdr 179structure is 180updated to account for the new address in the Routing header and the 181return value of the function is 0. 182Upon an error the return value of 183the function is -1. 184.\" 185.Ss inet6_rthdr_lasthop 186This function specifies the Strict/Loose flag for the final hop of a 187Routing header. 188For an IPv6 Type 0 Routing header, 189.Fa flags 190must be either 191.Dv IPV6_RTHDR_LOOSE 192or 193.Dv IPV6_RTHDR_STRICT . 194.Pp 195The return value of the function is 0 upon success, or -1 upon an error. 196.Pp 197Notice that a Routing header specifying 198.Li N 199intermediate nodes requires 200.Li N+1 201Strict/Loose flags. 202This requires 203.Li N 204calls to 205.Fn inet6_rthdr_add 206followed by one call to 207.Fn inet6_rthdr_lasthop . 208.\" 209.Ss inet6_rthdr_reverse 210This function is not yet implemented. 211When implemented, this should behave as follows. 212.Pp 213This function takes a Routing header that was received as ancillary 214data 215(pointed to by the first argument, 216.Fa in ) 217and writes a new Routing 218header that sends datagrams along the reverse of that route. 219Both 220arguments are allowed to point to the same buffer 221(that is, the reversal can occur in place). 222.Pp 223The return value of the function is 0 on success, or -1 upon an 224error. 225.\" 226.Ss inet6_rthdr_segments 227This function returns the number of segments 228(addresses) 229contained in 230the Routing header described by 231.Fa cmsg . 232On success the return value is 233between 1 and 23, inclusive. 234The return value of the function is -1 upon an error. 235.\" 236.Ss inet6_rthdr_getaddr 237This function returns a pointer to the IPv6 address specified by 238.Fa index 239(which must have a value between 1 and the value returned by 240.Fn inet6_rthdr_segments ) 241in the Routing header described by 242.Fa cmsg . 243An 244application should first call 245.Fn inet6_rthdr_segments 246to obtain the number of segments in the Routing header. 247.Pp 248Upon an error the return value of the function is 249.Dv NULL . 250.\" 251.Ss inet6_rthdr_getflags 252This function returns the flags value specified by 253.Fa index 254(which must 255have a value between 0 and the value returned by 256.Fn inet6_rthdr_segments ) 257in the Routing header described by 258.Fa cmsg . 259For an IPv6 Type 0 Routing header the return value will be either 260.Dv IPV6_RTHDR_LOOSE 261or 262.Dv IPV6_RTHDR_STRICT . 263.Pp 264Upon an error the return value of the function is -1. 265.Pp 266Note: Addresses are indexed starting at 1, and flags starting at 0, 267to maintain consistency with the terminology and figures in RFC2460. 268.\" 269.Sh DIAGNOSTICS 270.Fn inet6_rthdr_space 271returns 0 on errors. 272.Pp 273.Fn inet6_rthdr_add , 274.Fn inet6_rthdr_lasthop 275and 276.Fn inet6_rthdr_reverse 277return 0 on success, and returns -1 on error. 278.Pp 279.Fn inet6_rthdr_init 280and 281.Fn inet6_rthdr_getaddr 282return 283.Dv NULL 284on error. 285.Pp 286.Fn inet6_rthdr_segments 287and 288.Fn inet6_rthdr_getflags 289return -1 on error. 290.\" 291.Sh EXAMPLES 292RFC2292 gives comprehensive examples in chapter 8. 293.\" 294.Sh SEE ALSO 295.Rs 296.%A W. Stevens 297.%A M. Thomas 298.%T "Advanced Sockets API for IPv6" 299.%N RFC2292 300.%D February 1998 301.Re 302.Rs 303.%A S. Deering 304.%A R. Hinden 305.%T "Internet Protocol, Version 6 (IPv6) Specification" 306.%N RFC2460 307.%D December 1998 308.Re 309.\" 310.Sh HISTORY 311The implementation first appeared in KAME advanced networking kit. 312.\" 313.Sh STANDARDS 314The functions 315are documented in 316.Dq Advanced Sockets API for IPv6 317(RFC2292). 318.\" 319.Sh BUGS 320The text was shamelessly copied from RFC2292. 321.Pp 322.Fn inet6_rthdr_reverse 323is not implemented yet. 324