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.In 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 270The 271.Fn inet6_rthdr_space 272function 273returns 0 on errors. 274.Pp 275The 276.Fn inet6_rthdr_add , 277.Fn inet6_rthdr_lasthop 278and 279.Fn inet6_rthdr_reverse 280functions 281return 0 on success, and returns -1 on error. 282.Pp 283The 284.Fn inet6_rthdr_init 285and 286.Fn inet6_rthdr_getaddr 287functions 288return 289.Dv NULL 290on error. 291.Pp 292The 293.Fn inet6_rthdr_segments 294and 295.Fn inet6_rthdr_getflags 296functions 297return -1 on error. 298.\" 299.Sh EXAMPLES 300RFC2292 gives comprehensive examples in chapter 8. 301.\" 302.Sh SEE ALSO 303.Rs 304.%A W. Stevens 305.%A M. Thomas 306.%T "Advanced Sockets API for IPv6" 307.%N RFC2292 308.%D February 1998 309.Re 310.Rs 311.%A S. Deering 312.%A R. Hinden 313.%T "Internet Protocol, Version 6 (IPv6) Specification" 314.%N RFC2460 315.%D December 1998 316.Re 317.\" 318.Sh HISTORY 319The implementation first appeared in KAME advanced networking kit. 320.\" 321.Sh STANDARDS 322The functions 323are documented in 324.Dq Advanced Sockets API for IPv6 325(RFC2292). 326.\" 327.Sh BUGS 328The text was shamelessly copied from RFC2292. 329.Pp 330The 331.Fn inet6_rthdr_reverse 332function 333is not implemented yet. 334