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