1.\" $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $ 2.\" 3.\" Copyright (C) 2004 WIDE Project. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the project nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd December 24, 2004 33.Dt INET6_RTH_SPACE 3 34.Os 35.\" 36.Sh NAME 37.Nm inet6_rth_space , 38.Nm inet6_rth_init , 39.Nm inet6_rth_add , 40.Nm inet6_rth_reverse , 41.Nm inet6_rth_segments , 42.Nm inet6_rth_getaddr 43.Nd IPv6 Routing Header Options manipulation 44.\" 45.Sh SYNOPSIS 46.In netinet/in.h 47.Ft socklen_t 48.Fn inet6_rth_space "int" "int" 49.Ft "void *" 50.Fn inet6_rth_init "void *" "socklen_t" "int" "int" 51.Ft int 52.Fn inet6_rth_add "void *" "const struct in6_addr *" 53.Ft int 54.Fn inet6_rth_reverse "const void *" "void *" 55.Ft int 56.Fn inet6_rth_segments "const void *" 57.Ft "struct in6_addr *" 58.Fn inet6_rth_getaddr "const void *" "int" 59.\" 60.Sh DESCRIPTION 61The IPv6 Advanced API, RFC 3542, defines the functions that an 62application calls to build and examine IPv6 Routing headers. 63Routing headers are used to perform source routing in IPv6 networks. 64The RFC uses the word 65.Dq segments 66to describe addresses and that is the term used here as well. 67All of the functions are defined in the 68.In netinet/in.h 69header file. 70The functions described in this manual page all operate 71on routing header structures which are defined in 72.In netinet/ip6.h 73but which should not need to be modified outside the use of this API. 74The size and shape of the route header structures may change, so using 75the APIs is a more portable, long term, solution. 76.Pp 77The functions in the API are split into two groups, those that build a 78routing header and those that parse a received routing header. 79We will describe the builder functions followed by the parser functions. 80.Ss inet6_rth_space 81The 82.Fn inet6_rth_space 83function returns the number of bytes required to hold a Routing Header 84of the type, specified in the 85.Fa type 86argument and containing the number of addresses specified in the 87.Fa segments 88argument. 89When the type is 90.Dv IPV6_RTHDR_TYPE_0 91the number of segments must be from 0 through 127. 92Routing headers of type 93.Dv IPV6_RTHDR_TYPE_2 94contain only one segment, and are only used with Mobile IPv6. 95The return value from this function is the number of bytes required to 96store the routing header. 97If the value 0 is returned then either the 98route header type was not recognized or another error occurred. 99.Ss inet6_rth_init 100The 101.Fn inet6_rth_init 102function initializes the pre-allocated buffer pointed to by 103.Fa bp 104to contain a routing header of the specified type. 105The 106.Fa bp_len 107argument is used to verify that the buffer is large enough. 108The caller must allocate the buffer pointed to by bp. 109The necessary buffer size should be determined by calling 110.Fn inet6_rth_space 111described in the previous sections. 112.Pp 113The 114.Fn inet6_rth_init 115function returns a pointer to 116.Fa bp 117on success and 118.Dv NULL 119when there is an error. 120.Ss inet6_rth_add 121The 122.Fn inet6_rth_add 123function adds the IPv6 address pointed to by 124.Fa addr 125to the end of the routing header being constructed. 126.Pp 127A successful addition results in the function returning 0, otherwise 128\-1 is returned. 129.Ss inet6_rth_reverse 130The 131.Fn inet6_rth_reverse 132function takes a routing header, pointed to by the 133argument 134.Fa in , 135and writes a new routing header into the argument pointed to by 136.Fa out . 137The routing header at that sends datagrams along the reverse of that 138route. 139Both arguments are allowed to point to the same buffer meaning 140that the reversal can occur in place. 141.Pp 142The return value of the function is 0 on success, or \-1 when 143there is an error. 144.\" 145.Pp 146The next set of functions operate on a routing header that the 147application wants to parse. 148In the usual case such a routing header 149is received from the network, although these functions can also be 150used with routing headers that the application itself created. 151.Ss inet6_rth_segments 152The 153.Fn inet6_rth_segments 154function returns the number of segments contained in the 155routing header pointed to by 156.Fa bp . 157The return value is the number of segments contained in the routing 158header, or \-1 if an error occurred. 159It is not an error for 0 to be 160returned as a routing header may contain 0 segments. 161.\" 162.Ss inet6_rth_getaddr 163The 164.Fn inet6_rth_getaddr 165function is used to retrieve a single address from a routing header. 166The 167.Fa index 168is the location in the routing header from which the application wants 169to retrieve an address. 170The 171.Fa index 172parameter must have a value between 0 and one less than the number of 173segments present in the routing header. 174The 175.Fn inet6_rth_segments 176function, described in the last section, should be used to determine 177the total number of segments in the routing header. 178The 179.Fn inet6_rth_getaddr 180function returns a pointer to an IPv6 address on success or 181.Dv NULL 182when an error has occurred. 183.\" 184.Sh EXAMPLES 185RFC 3542 gives extensive examples in Section 21, Appendix B. 186.Pp 187KAME also provides examples in the advapitest directory of its kit. 188.\" 189.Sh DIAGNOSTICS 190The 191.Fn inet6_rth_space 192and 193.Fn inet6_rth_getaddr 194functions return 0 on errors. 195.Pp 196The 197.Fn inet6_rthdr_init 198function returns 199.Dv NULL 200on error. 201The 202.Fn inet6_rth_add 203and 204.Fn inet6_rth_reverse 205functions return 0 on success, or \-1 upon an error. 206.\" 207.Sh SEE ALSO 208.Rs 209.%A W. Stevens 210.%A M. Thomas 211.%A E. Nordmark 212.%A T. Jinmei 213.%T "Advanced Sockets API for IPv6" 214.%N RFC 3542 215.%D May 2003 216.Re 217.Rs 218.%A S. Deering 219.%A R. Hinden 220.%T "Internet Protocol, Version 6 (IPv6) Specification" 221.%N RFC2460 222.%D December 1998 223.Re 224.Sh HISTORY 225The implementation first appeared in KAME advanced networking kit. 226