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 The 105.Fa bp_len 106argument is used to verify that the buffer is large enough. 107The caller must allocate the buffer pointed to by bp. 108The necessary buffer size should be determined by calling 109.Fn inet6_rth_space 110described in the previous sections. 111.Pp 112The 113.Fn inet6_rth_init 114function returns a pointer to 115.Fa bp 116on success and 117.Dv NULL 118when there is an error. 119.Ss inet6_rth_add 120The 121.Fn inet6_rth_add 122function adds the IPv6 address pointed to by 123.Fa addr 124to the end of the routing header being constructed. 125.Pp 126A successful addition results in the function returning 0, otherwise 127\-1 is returned. 128.Ss inet6_rth_reverse 129The 130.Fn inet6_rth_reverse 131function takes a routing header, pointed to by the 132argument 133.Fa in , 134and writes a new routing header into the argument pointed to by 135.Fa out . 136The routing header at that sends datagrams along the reverse of that 137route. 138Both arguments are allowed to point to the same buffer meaning 139that the reversal can occur in place. 140.Pp 141The return value of the function is 0 on success, or \-1 when 142there is an error. 143.\" 144.Pp 145The next set of functions operate on a routing header that the 146application wants to parse. 147In the usual case such a routing header 148is received from the network, although these functions can also be 149used with routing headers that the application itself created. 150.Ss inet6_rth_segments 151The 152.Fn inet6_rth_segments 153function returns the number of segments contained in the 154routing header pointed to by 155.Fa bp . 156The return value is the number of segments contained in the routing 157header, or \-1 if an error occurred. 158It is not an error for 0 to be 159returned as a routing header may contain 0 segments. 160.\" 161.Ss inet6_rth_getaddr 162The 163.Fn inet6_rth_getaddr 164function is used to retrieve a single address from a routing header. 165The 166.Fa index 167is the location in the routing header from which the application wants 168to retrieve an address. 169The 170.Fa index 171parameter must have a value between 0 and one less than the number of 172segments present in the routing header. 173The 174.Fn inet6_rth_segments 175function, described in the last section, should be used to determine 176the total number of segments in the routing header. 177The 178.Fn inet6_rth_getaddr 179function returns a pointer to an IPv6 address on success or 180.Dv NULL 181when an error has occurred. 182.\" 183.Sh EXAMPLES 184RFC 3542 gives extensive examples in Section 21, Appendix B. 185.Pp 186KAME also provides examples in the advapitest directory of its kit. 187.\" 188.Sh DIAGNOSTICS 189The 190.Fn inet6_rth_space 191and 192.Fn inet6_rth_getaddr 193functions return 0 on errors. 194.Pp 195The 196.Fn inet6_rthdr_init 197function returns 198.Dv NULL 199on error. 200The 201.Fn inet6_rth_add 202and 203.Fn inet6_rth_reverse 204functions return 0 on success, or \-1 upon an error. 205.\" 206.Sh SEE ALSO 207.Rs 208.%A W. Stevens 209.%A M. Thomas 210.%A E. Nordmark 211.%A T. Jinmei 212.%T "Advanced Sockets API for IPv6" 213.%N RFC 3542 214.%D May 2003 215.Re 216.Rs 217.%A S. Deering 218.%A R. Hinden 219.%T "Internet Protocol, Version 6 (IPv6) Specification" 220.%N RFC2460 221.%D December 1998 222.Re 223.Sh HISTORY 224The implementation first appeared in KAME advanced networking kit. 225