1.\" $NetBSD: inet6_rth_space.3,v 1.4 2024/03/17 21:37:53 andvar Exp $ 2.\" $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $ 3.\" 4.\" Copyright (C) 2004 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.Dd December 24, 2004 32.Dt INET6_RTH_SPACE 3 33.Os 34.\" 35.Sh NAME 36.Nm inet6_rth_space , 37.Nm inet6_rth_init , 38.Nm inet6_rth_add , 39.Nm inet6_rth_reverse , 40.Nm inet6_rth_segments , 41.Nm inet6_rth_getaddr 42.Nd IPv6 Routing Header Options manipulation 43.\" 44.Sh SYNOPSIS 45.In netinet/in.h 46.Ft socklen_t 47.Fn inet6_rth_space "int" "int" 48.Ft "void *" 49.Fn inet6_rth_init "void *" "socklen_t" "int" "int" 50.Ft int 51.Fn inet6_rth_add "void *" "const struct in6_addr *" 52.Ft int 53.Fn inet6_rth_reverse "const void *" "void *" 54.Ft int 55.Fn inet6_rth_segments "const void *" 56.Ft "struct in6_addr *" 57.Fn inet6_rth_getaddr "const void *" "int" 58.\" 59.Sh DESCRIPTION 60The IPv6 Advanced API, RFC 3542, defines the functions that an 61application calls to build and examine IPv6 Routing headers. 62Routing headers are used to perform source routing in IPv6 networks. 63The RFC uses the word 64.Dq segments 65to describe addresses and that is the term used here as well. 66All of the functions are defined in the 67.In netinet/in.h 68header file. 69The functions described in this manual page all operate 70on routing header structures which are defined in 71.In netinet/ip6.h 72but which should not need to be modified outside the use of this API. 73The size and shape of the route header structures may change, so using 74the APIs is a more portable, long term, solution. 75.Pp 76The functions in the API are split into two groups, those that build a 77routing header and those that parse a received routing header. 78We will describe the builder functions followed by the parser functions. 79.Ss inet6_rth_space 80The 81.Fn inet6_rth_space 82function returns the number of bytes required to hold a Routing Header 83of the type, specified in the 84.Fa type 85argument and containing the number of addresses specified in the 86.Fa segments 87argument. 88When the type is 89.Dv IPV6_RTHDR_TYPE_0 90the number of segments must be from 0 through 127. 91Routing headers of type 92.Dv IPV6_RTHDR_TYPE_2 93contain only one segment, and are only used with Mobile IPv6. 94The return value from this function is the number of bytes required to 95store the routing header. 96If the value 0 is returned then either the 97route header type was not recognized or another error occurred. 98.Ss inet6_rth_init 99The 100.Fn inet6_rth_init 101function initializes the pre-allocated buffer pointed to by 102.Fa bp 103to contain a routing header of the specified type The 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 RETURN VALUES 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