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