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.Dd December 24, 2004 31.Dt INET6_RTH_SPACE 3 32.Os 33.\" 34.Sh NAME 35.Nm inet6_rth_space , 36.Nm inet6_rth_init , 37.Nm inet6_rth_add , 38.Nm inet6_rth_reverse , 39.Nm inet6_rth_segments , 40.Nm inet6_rth_getaddr 41.Nd IPv6 Routing Header Options manipulation 42.\" 43.Sh SYNOPSIS 44.In netinet/in.h 45.Ft socklen_t 46.Fn inet6_rth_space "int" "int" 47.Ft "void *" 48.Fn inet6_rth_init "void *" "socklen_t" "int" "int" 49.Ft int 50.Fn inet6_rth_add "void *" "const struct in6_addr *" 51.Ft int 52.Fn inet6_rth_reverse "const void *" "void *" 53.Ft int 54.Fn inet6_rth_segments "const void *" 55.Ft "struct in6_addr *" 56.Fn inet6_rth_getaddr "const void *" "int" 57.\" 58.Sh DESCRIPTION 59The IPv6 Advanced API, RFC 3542, defines the functions that an 60application calls to build and examine IPv6 Routing headers. 61Routing headers are used to perform source routing in IPv6 networks. 62The RFC uses the word 63.Dq segments 64to describe addresses and that is the term used here as well. 65All of the functions are defined in the 66.In netinet/in.h 67header file. 68The functions described in this manual page all operate 69on routing header structures which are defined in 70.In netinet/ip6.h 71but which should not need to be modified outside the use of this API. 72The size and shape of the route header structures may change, so using 73the APIs is a more portable, long term, solution. 74.Pp 75The functions in the API are split into two groups, those that build a 76routing header and those that parse a received routing header. 77We will describe the builder functions followed by the parser functions. 78.Ss inet6_rth_space 79The 80.Fn inet6_rth_space 81function returns the number of bytes required to hold a Routing Header 82of the type, specified in the 83.Fa type 84argument and containing the number of addresses specified in the 85.Fa segments 86argument. 87When the type is 88.Dv IPV6_RTHDR_TYPE_0 89the number of segments must be from 0 through 127. 90Routing headers of type 91.Dv IPV6_RTHDR_TYPE_2 92contain only one segment, and are only used with Mobile IPv6. 93The return value from this function is the number of bytes required to 94store the routing header. 95If the value 0 is returned then either the 96route header type was not recognized or another error occurred. 97.Ss inet6_rth_init 98The 99.Fn inet6_rth_init 100function initializes the pre-allocated buffer pointed to by 101.Fa bp 102to contain a routing header of the specified type. 103The 104.Fa bp_len 105argument is used to verify that the buffer is large enough. 106The caller must allocate the buffer pointed to by bp. 107The necessary buffer size should be determined by calling 108.Fn inet6_rth_space 109described in the previous sections. 110.Pp 111The 112.Fn inet6_rth_init 113function returns a pointer to 114.Fa bp 115on success and 116.Dv NULL 117when there is an error. 118.Ss inet6_rth_add 119The 120.Fn inet6_rth_add 121function adds the IPv6 address pointed to by 122.Fa addr 123to the end of the routing header being constructed. 124.Pp 125A successful addition results in the function returning 0, otherwise 126\-1 is returned. 127.Ss inet6_rth_reverse 128The 129.Fn inet6_rth_reverse 130function takes a routing header, pointed to by the 131argument 132.Fa in , 133and writes a new routing header into the argument pointed to by 134.Fa out . 135The routing header at that sends datagrams along the reverse of that 136route. 137Both arguments are allowed to point to the same buffer meaning 138that the reversal can occur in place. 139.Pp 140The return value of the function is 0 on success, or \-1 when 141there is an error. 142.\" 143.Pp 144The next set of functions operate on a routing header that the 145application wants to parse. 146In the usual case such a routing header 147is received from the network, although these functions can also be 148used with routing headers that the application itself created. 149.Ss inet6_rth_segments 150The 151.Fn inet6_rth_segments 152function returns the number of segments contained in the 153routing header pointed to by 154.Fa bp . 155The return value is the number of segments contained in the routing 156header, or \-1 if an error occurred. 157It is not an error for 0 to be 158returned as a routing header may contain 0 segments. 159.\" 160.Ss inet6_rth_getaddr 161The 162.Fn inet6_rth_getaddr 163function is used to retrieve a single address from a routing header. 164The 165.Fa index 166is the location in the routing header from which the application wants 167to retrieve an address. 168The 169.Fa index 170parameter must have a value between 0 and one less than the number of 171segments present in the routing header. 172The 173.Fn inet6_rth_segments 174function, described in the last section, should be used to determine 175the total number of segments in the routing header. 176The 177.Fn inet6_rth_getaddr 178function returns a pointer to an IPv6 address on success or 179.Dv NULL 180when an error has occurred. 181.\" 182.Sh EXAMPLES 183RFC 3542 gives extensive examples in Section 21, Appendix B. 184.Pp 185KAME also provides examples in the advapitest directory of its kit. 186.\" 187.Sh DIAGNOSTICS 188The 189.Fn inet6_rth_space 190and 191.Fn inet6_rth_getaddr 192functions return 0 on errors. 193.Pp 194The 195.Fn inet6_rthdr_init 196function returns 197.Dv NULL 198on error. 199The 200.Fn inet6_rth_add 201and 202.Fn inet6_rth_reverse 203functions return 0 on success, or \-1 upon an error. 204.\" 205.Sh SEE ALSO 206.Rs 207.%A W. Stevens 208.%A M. Thomas 209.%A E. Nordmark 210.%A T. Jinmei 211.%T "Advanced Sockets API for IPv6" 212.%N RFC 3542 213.%D May 2003 214.Re 215.Rs 216.%A S. Deering 217.%A R. Hinden 218.%T "Internet Protocol, Version 6 (IPv6) Specification" 219.%N RFC2460 220.%D December 1998 221.Re 222.Sh HISTORY 223The implementation first appeared in KAME advanced networking kit. 224