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: src/lib/libc/net/inet6_rthdr_space.3,v 1.1.2.6 2001/12/14 18:33:55 ru Exp $ 34.\" $DragonFly: src/lib/libc/net/inet6_rthdr_space.3,v 1.2 2003/06/17 04:26:44 dillon Exp $ 35.\" 36.Dd December 10, 1999 37.Dt INET6_RTHDR_SPACE 3 38.Os 39.\" 40.Sh NAME 41.Nm inet6_rthdr_space , 42.Nm inet6_rthdr_init , 43.Nm inet6_rthdr_add , 44.Nm inet6_rthdr_lasthop , 45.Nm inet6_rthdr_reverse , 46.Nm inet6_rthdr_segments , 47.Nm inet6_rthdr_getaddr , 48.Nm inet6_rthdr_getflags 49.Nd IPv6 Routing Header Options manipulation 50.\" 51.Sh LIBRARY 52.Lb libc 53.Sh SYNOPSIS 54.In sys/types.h 55.In netinet/in.h 56.Ft size_t 57.Fn inet6_rthdr_space "int type" "int segments" 58.Ft "struct cmsghdr *" 59.Fn inet6_rthdr_init "void *bp" "int type" 60.Ft int 61.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags" 62.Ft int 63.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags" 64.Ft int 65.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out" 66.Ft int 67.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg" 68.Ft "struct in6_addr *" 69.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index" 70.Ft int 71.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index" 72.\" 73.Sh DESCRIPTION 74RFC2292 IPv6 advanced API defines eight 75functions that the application calls to build and examine a Routing 76header. Four functions build a Routing header: 77.Bl -hang 78.It Fn inet6_rthdr_space 79return #bytes required for ancillary data 80.It Fn inet6_rthdr_init 81initialize ancillary data for Routing header 82.It Fn inet6_rthdr_add 83add IPv6 address & flags to Routing header 84.It Fn inet6_rthdr_lasthop 85specify the flags for the final hop 86.El 87.Pp 88Four functions deal with a returned Routing header: 89.Bl -hang 90.It Fn inet6_rthdr_reverse 91reverse a Routing header 92.It Fn inet6_rthdr_segments 93return #segments in a Routing header 94.It Fn inet6_rthdr_getaddr 95fetch one address from a Routing header 96.It Fn inet6_rthdr_getflags 97fetch one flag from a Routing header 98.El 99.Pp 100The function prototypes for these functions are all in the 101.Aq Li netinet/in.h 102header. 103.\" 104.Ss inet6_rthdr_space 105This function returns the number of bytes required to hold a Routing 106header of the specified 107.Fa type 108containing the specified number of 109.Fa segments 110(addresses). 111For an IPv6 Type 0 Routing header, the number 112of segments must be between 1 and 23, inclusive. The return value 113includes the size of the cmsghdr structure that precedes the Routing 114header, and any required padding. 115.Pp 116If the return value is 0, then either the type of the Routing header 117is not supported by this implementation or the number of segments is 118invalid for this type of Routing header. 119.Pp 120Note: This function returns the size but does not allocate the space 121required for the ancillary data. 122This allows an application to 123allocate a larger buffer, if other ancillary data objects are 124desired, since all the ancillary data objects must be specified to 125.Xr sendmsg 2 126as a single 127.Li msg_control 128buffer. 129.\" 130.Ss inet6_rthdr_init 131This function initializes the buffer pointed to by 132.Fa bp 133to contain a 134.Li cmsghdr 135structure followed by a Routing header of the specified 136.Fa type . 137The 138.Li cmsg_len 139member of the 140.Li cmsghdr 141structure is initialized to the 142size of the structure plus the amount of space required by the 143Routing header. 144The 145.Li cmsg_level 146and 147.Li cmsg_type 148members are also initialized as required. 149.Pp 150The caller must allocate the buffer and its size can be determined by 151calling 152.Fn inet6_rthdr_space . 153.Pp 154Upon success the return value is the pointer to the 155.Li cmsghdr 156structure, and this is then used as the first argument to the next 157two functions. 158Upon an error the return value is 159.Dv NULL . 160.\" 161.Ss inet6_rthdr_add 162This function adds the address pointed to by 163.Fa addr 164to the end of the 165Routing header being constructed and sets the type of this hop to the 166value of 167.Fa flags . 168For an IPv6 Type 0 Routing header, 169.Fa flags 170must be 171either 172.Dv IPV6_RTHDR_LOOSE 173or 174.Dv IPV6_RTHDR_STRICT . 175.Pp 176If successful, the 177.Li cmsg_len 178member of the 179.Li cmsghdr 180structure is 181updated to account for the new address in the Routing header and the 182return value of the function is 0. 183Upon an error the return value of 184the function is -1. 185.\" 186.Ss inet6_rthdr_lasthop 187This function specifies the Strict/Loose flag for the final hop of a 188Routing header. 189For an IPv6 Type 0 Routing header, 190.Fa flags 191must be either 192.Dv IPV6_RTHDR_LOOSE 193or 194.Dv IPV6_RTHDR_STRICT . 195.Pp 196The return value of the function is 0 upon success, or -1 upon an error. 197.Pp 198Notice that a Routing header specifying 199.Li N 200intermediate nodes requires 201.Li N+1 202Strict/Loose flags. 203This requires 204.Li N 205calls to 206.Fn inet6_rthdr_add 207followed by one call to 208.Fn inet6_rthdr_lasthop . 209.\" 210.Ss inet6_rthdr_reverse 211This function is not yet implemented. 212When implemented, this should behave as follows. 213.Pp 214This function takes a Routing header that was received as ancillary 215data 216(pointed to by the first argument, 217.Fa in ) 218and writes a new Routing 219header that sends datagrams along the reverse of that route. 220Both 221arguments are allowed to point to the same buffer 222(that is, the reversal can occur in place). 223.Pp 224The return value of the function is 0 on success, or -1 upon an 225error. 226.\" 227.Ss inet6_rthdr_segments 228This function returns the number of segments 229(addresses) 230contained in 231the Routing header described by 232.Fa cmsg . 233On success the return value is 234between 1 and 23, inclusive. 235The return value of the function is -1 upon an error. 236.\" 237.Ss inet6_rthdr_getaddr 238This function returns a pointer to the IPv6 address specified by 239.Fa index 240(which must have a value between 1 and the value returned by 241.Fn inet6_rthdr_segments ) 242in the Routing header described by 243.Fa cmsg . 244An 245application should first call 246.Fn inet6_rthdr_segments 247to obtain the number of segments in the Routing header. 248.Pp 249Upon an error the return value of the function is 250.Dv NULL . 251.\" 252.Ss inet6_rthdr_getflags 253This function returns the flags value specified by 254.Fa index 255(which must 256have a value between 0 and the value returned by 257.Fn inet6_rthdr_segments ) 258in the Routing header described by 259.Fa cmsg . 260For an IPv6 Type 0 Routing header the return value will be either 261.Dv IPV6_RTHDR_LOOSE 262or 263.Dv IPV6_RTHDR_STRICT . 264.Pp 265Upon an error the return value of the function is -1. 266.Pp 267Note: Addresses are indexed starting at 1, and flags starting at 0, 268to maintain consistency with the terminology and figures in RFC2460. 269.\" 270.Sh DIAGNOSTICS 271.Fn inet6_rthdr_space 272returns 0 on errors. 273.Pp 274.Fn inet6_rthdr_add , 275.Fn inet6_rthdr_lasthop 276and 277.Fn inet6_rthdr_reverse 278return 0 on success, and returns -1 on error. 279.Pp 280.Fn inet6_rthdr_init 281and 282.Fn inet6_rthdr_getaddr 283return 284.Dv NULL 285on error. 286.Pp 287.Fn inet6_rthdr_segments 288and 289.Fn inet6_rthdr_getflags 290return -1 on error. 291.\" 292.Sh EXAMPLES 293RFC2292 gives comprehensive examples in chapter 8. 294.\" 295.Sh SEE ALSO 296.Rs 297.%A W. Stevens 298.%A M. Thomas 299.%T "Advanced Sockets API for IPv6" 300.%N RFC2292 301.%D February 1998 302.Re 303.Rs 304.%A S. Deering 305.%A R. Hinden 306.%T "Internet Protocol, Version 6 (IPv6) Specification" 307.%N RFC2460 308.%D December 1998 309.Re 310.\" 311.Sh HISTORY 312The implementation first appeared in KAME advanced networking kit. 313.\" 314.Sh STANDARDS 315The functions 316are documented in 317.Dq Advanced Sockets API for IPv6 318(RFC2292). 319.\" 320.Sh BUGS 321The text was shamelessly copied from RFC2292. 322.Pp 323.Fn inet6_rthdr_reverse 324is not implemented yet. 325