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