16617cf57SGeorge V. Neville-Neil.\" $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $ 26617cf57SGeorge V. Neville-Neil.\" 36617cf57SGeorge V. Neville-Neil.\" Copyright (C) 2004 WIDE Project. 46617cf57SGeorge V. Neville-Neil.\" All rights reserved. 56617cf57SGeorge V. Neville-Neil.\" 66617cf57SGeorge V. Neville-Neil.\" Redistribution and use in source and binary forms, with or without 76617cf57SGeorge V. Neville-Neil.\" modification, are permitted provided that the following conditions 86617cf57SGeorge V. Neville-Neil.\" are met: 96617cf57SGeorge V. Neville-Neil.\" 1. Redistributions of source code must retain the above copyright 106617cf57SGeorge V. Neville-Neil.\" notice, this list of conditions and the following disclaimer. 116617cf57SGeorge V. Neville-Neil.\" 2. Redistributions in binary form must reproduce the above copyright 126617cf57SGeorge V. Neville-Neil.\" notice, this list of conditions and the following disclaimer in the 136617cf57SGeorge V. Neville-Neil.\" documentation and/or other materials provided with the distribution. 146617cf57SGeorge V. Neville-Neil.\" 3. Neither the name of the project nor the names of its contributors 156617cf57SGeorge V. Neville-Neil.\" may be used to endorse or promote products derived from this software 166617cf57SGeorge V. Neville-Neil.\" without specific prior written permission. 176617cf57SGeorge V. Neville-Neil.\" 186617cf57SGeorge V. Neville-Neil.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 196617cf57SGeorge V. Neville-Neil.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 206617cf57SGeorge V. Neville-Neil.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 216617cf57SGeorge V. Neville-Neil.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 226617cf57SGeorge V. Neville-Neil.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 236617cf57SGeorge V. Neville-Neil.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 246617cf57SGeorge V. Neville-Neil.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 256617cf57SGeorge V. Neville-Neil.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 266617cf57SGeorge V. Neville-Neil.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 276617cf57SGeorge V. Neville-Neil.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 286617cf57SGeorge V. Neville-Neil.\" SUCH DAMAGE. 296617cf57SGeorge V. Neville-Neil.\" 306617cf57SGeorge V. Neville-Neil.Dd December 24, 2004 316617cf57SGeorge V. Neville-Neil.Dt INET6_RTH_SPACE 3 326617cf57SGeorge V. Neville-Neil.Os 336617cf57SGeorge V. Neville-Neil.\" 346617cf57SGeorge V. Neville-Neil.Sh NAME 356617cf57SGeorge V. Neville-Neil.Nm inet6_rth_space , 366617cf57SGeorge V. Neville-Neil.Nm inet6_rth_init , 376617cf57SGeorge V. Neville-Neil.Nm inet6_rth_add , 386617cf57SGeorge V. Neville-Neil.Nm inet6_rth_reverse , 396617cf57SGeorge V. Neville-Neil.Nm inet6_rth_segments , 406617cf57SGeorge V. Neville-Neil.Nm inet6_rth_getaddr 416617cf57SGeorge V. Neville-Neil.Nd IPv6 Routing Header Options manipulation 426617cf57SGeorge V. Neville-Neil.\" 436617cf57SGeorge V. Neville-Neil.Sh SYNOPSIS 446617cf57SGeorge V. Neville-Neil.In netinet/in.h 456617cf57SGeorge V. Neville-Neil.Ft socklen_t 466617cf57SGeorge V. Neville-Neil.Fn inet6_rth_space "int" "int" 476617cf57SGeorge V. Neville-Neil.Ft "void *" 486617cf57SGeorge V. Neville-Neil.Fn inet6_rth_init "void *" "socklen_t" "int" "int" 496617cf57SGeorge V. Neville-Neil.Ft int 506617cf57SGeorge V. Neville-Neil.Fn inet6_rth_add "void *" "const struct in6_addr *" 516617cf57SGeorge V. Neville-Neil.Ft int 526617cf57SGeorge V. Neville-Neil.Fn inet6_rth_reverse "const void *" "void *" 536617cf57SGeorge V. Neville-Neil.Ft int 546617cf57SGeorge V. Neville-Neil.Fn inet6_rth_segments "const void *" 556617cf57SGeorge V. Neville-Neil.Ft "struct in6_addr *" 566617cf57SGeorge V. Neville-Neil.Fn inet6_rth_getaddr "const void *" "int" 576617cf57SGeorge V. Neville-Neil.\" 586617cf57SGeorge V. Neville-Neil.Sh DESCRIPTION 596617cf57SGeorge V. Neville-NeilThe IPv6 Advanced API, RFC 3542, defines the functions that an 606617cf57SGeorge V. Neville-Neilapplication calls to build and examine IPv6 Routing headers. 616617cf57SGeorge V. Neville-NeilRouting headers are used to perform source routing in IPv6 networks. 626617cf57SGeorge V. Neville-NeilThe RFC uses the word 636617cf57SGeorge V. Neville-Neil.Dq segments 646617cf57SGeorge V. Neville-Neilto describe addresses and that is the term used here as well. 656617cf57SGeorge V. Neville-NeilAll of the functions are defined in the 666617cf57SGeorge V. Neville-Neil.In netinet/in.h 676617cf57SGeorge V. Neville-Neilheader file. 686617cf57SGeorge V. Neville-NeilThe functions described in this manual page all operate 696617cf57SGeorge V. Neville-Neilon routing header structures which are defined in 706617cf57SGeorge V. Neville-Neil.In netinet/ip6.h 716617cf57SGeorge V. Neville-Neilbut which should not need to be modified outside the use of this API. 726617cf57SGeorge V. Neville-NeilThe size and shape of the route header structures may change, so using 736617cf57SGeorge V. Neville-Neilthe APIs is a more portable, long term, solution. 746617cf57SGeorge V. Neville-Neil.Pp 756617cf57SGeorge V. Neville-NeilThe functions in the API are split into two groups, those that build a 766617cf57SGeorge V. Neville-Neilrouting header and those that parse a received routing header. 776617cf57SGeorge V. Neville-NeilWe will describe the builder functions followed by the parser functions. 786617cf57SGeorge V. Neville-Neil.Ss inet6_rth_space 796617cf57SGeorge V. Neville-NeilThe 806617cf57SGeorge V. Neville-Neil.Fn inet6_rth_space 816617cf57SGeorge V. Neville-Neilfunction returns the number of bytes required to hold a Routing Header 826617cf57SGeorge V. Neville-Neilof the type, specified in the 836617cf57SGeorge V. Neville-Neil.Fa type 846617cf57SGeorge V. Neville-Neilargument and containing the number of addresses specified in the 856617cf57SGeorge V. Neville-Neil.Fa segments 866fb9b618SGiorgos Keramidasargument. 876617cf57SGeorge V. Neville-NeilWhen the type is 886617cf57SGeorge V. Neville-Neil.Dv IPV6_RTHDR_TYPE_0 896617cf57SGeorge V. Neville-Neilthe number of segments must be from 0 through 127. 906617cf57SGeorge V. Neville-NeilRouting headers of type 916617cf57SGeorge V. Neville-Neil.Dv IPV6_RTHDR_TYPE_2 926617cf57SGeorge V. Neville-Neilcontain only one segment, and are only used with Mobile IPv6. 936617cf57SGeorge V. Neville-NeilThe return value from this function is the number of bytes required to 946617cf57SGeorge V. Neville-Neilstore the routing header. 956617cf57SGeorge V. Neville-NeilIf the value 0 is returned then either the 966617cf57SGeorge V. Neville-Neilroute header type was not recognized or another error occurred. 976617cf57SGeorge V. Neville-Neil.Ss inet6_rth_init 986617cf57SGeorge V. Neville-NeilThe 996617cf57SGeorge V. Neville-Neil.Fn inet6_rth_init 1006617cf57SGeorge V. Neville-Neilfunction initializes the pre-allocated buffer pointed to by 1016617cf57SGeorge V. Neville-Neil.Fa bp 102c2025a76SJoel Dahlto contain a routing header of the specified type. 103c2025a76SJoel DahlThe 1046617cf57SGeorge V. Neville-Neil.Fa bp_len 1056617cf57SGeorge V. Neville-Neilargument is used to verify that the buffer is large enough. 1066617cf57SGeorge V. Neville-NeilThe caller must allocate the buffer pointed to by bp. 1076617cf57SGeorge V. Neville-NeilThe necessary buffer size should be determined by calling 1086617cf57SGeorge V. Neville-Neil.Fn inet6_rth_space 1096617cf57SGeorge V. Neville-Neildescribed in the previous sections. 1106617cf57SGeorge V. Neville-Neil.Pp 1116617cf57SGeorge V. Neville-NeilThe 1126617cf57SGeorge V. Neville-Neil.Fn inet6_rth_init 1136617cf57SGeorge V. Neville-Neilfunction returns a pointer to 1146617cf57SGeorge V. Neville-Neil.Fa bp 1156617cf57SGeorge V. Neville-Neilon success and 1166617cf57SGeorge V. Neville-Neil.Dv NULL 1176617cf57SGeorge V. Neville-Neilwhen there is an error. 1186617cf57SGeorge V. Neville-Neil.Ss inet6_rth_add 1196617cf57SGeorge V. Neville-NeilThe 1206617cf57SGeorge V. Neville-Neil.Fn inet6_rth_add 1216617cf57SGeorge V. Neville-Neilfunction adds the IPv6 address pointed to by 1226617cf57SGeorge V. Neville-Neil.Fa addr 1236617cf57SGeorge V. Neville-Neilto the end of the routing header being constructed. 1246617cf57SGeorge V. Neville-Neil.Pp 1256617cf57SGeorge V. Neville-NeilA successful addition results in the function returning 0, otherwise 1266617cf57SGeorge V. Neville-Neil\-1 is returned. 1276617cf57SGeorge V. Neville-Neil.Ss inet6_rth_reverse 1286617cf57SGeorge V. Neville-NeilThe 1296617cf57SGeorge V. Neville-Neil.Fn inet6_rth_reverse 1306617cf57SGeorge V. Neville-Neilfunction takes a routing header, pointed to by the 1316617cf57SGeorge V. Neville-Neilargument 1326617cf57SGeorge V. Neville-Neil.Fa in , 1336617cf57SGeorge V. Neville-Neiland writes a new routing header into the argument pointed to by 1346617cf57SGeorge V. Neville-Neil.Fa out . 1356617cf57SGeorge V. Neville-NeilThe routing header at that sends datagrams along the reverse of that 1366617cf57SGeorge V. Neville-Neilroute. 1376617cf57SGeorge V. Neville-NeilBoth arguments are allowed to point to the same buffer meaning 1386617cf57SGeorge V. Neville-Neilthat the reversal can occur in place. 1396617cf57SGeorge V. Neville-Neil.Pp 1406617cf57SGeorge V. Neville-NeilThe return value of the function is 0 on success, or \-1 when 1416617cf57SGeorge V. Neville-Neilthere is an error. 1426617cf57SGeorge V. Neville-Neil.\" 1436617cf57SGeorge V. Neville-Neil.Pp 1446617cf57SGeorge V. Neville-NeilThe next set of functions operate on a routing header that the 1456617cf57SGeorge V. Neville-Neilapplication wants to parse. 1466617cf57SGeorge V. Neville-NeilIn the usual case such a routing header 1476617cf57SGeorge V. Neville-Neilis received from the network, although these functions can also be 1486617cf57SGeorge V. Neville-Neilused with routing headers that the application itself created. 1496617cf57SGeorge V. Neville-Neil.Ss inet6_rth_segments 1506617cf57SGeorge V. Neville-NeilThe 1516617cf57SGeorge V. Neville-Neil.Fn inet6_rth_segments 1526617cf57SGeorge V. Neville-Neilfunction returns the number of segments contained in the 1536617cf57SGeorge V. Neville-Neilrouting header pointed to by 1546617cf57SGeorge V. Neville-Neil.Fa bp . 1556617cf57SGeorge V. Neville-NeilThe return value is the number of segments contained in the routing 1566617cf57SGeorge V. Neville-Neilheader, or \-1 if an error occurred. 1576617cf57SGeorge V. Neville-NeilIt is not an error for 0 to be 1586617cf57SGeorge V. Neville-Neilreturned as a routing header may contain 0 segments. 1596617cf57SGeorge V. Neville-Neil.\" 1606617cf57SGeorge V. Neville-Neil.Ss inet6_rth_getaddr 1616617cf57SGeorge V. Neville-NeilThe 1626617cf57SGeorge V. Neville-Neil.Fn inet6_rth_getaddr 1636617cf57SGeorge V. Neville-Neilfunction is used to retrieve a single address from a routing header. 1646617cf57SGeorge V. Neville-NeilThe 1656617cf57SGeorge V. Neville-Neil.Fa index 1666617cf57SGeorge V. Neville-Neilis the location in the routing header from which the application wants 1676617cf57SGeorge V. Neville-Neilto retrieve an address. 1686617cf57SGeorge V. Neville-NeilThe 1696617cf57SGeorge V. Neville-Neil.Fa index 1706617cf57SGeorge V. Neville-Neilparameter must have a value between 0 and one less than the number of 1716617cf57SGeorge V. Neville-Neilsegments present in the routing header. 1726617cf57SGeorge V. Neville-NeilThe 1736617cf57SGeorge V. Neville-Neil.Fn inet6_rth_segments 1746617cf57SGeorge V. Neville-Neilfunction, described in the last section, should be used to determine 1756617cf57SGeorge V. Neville-Neilthe total number of segments in the routing header. 1766617cf57SGeorge V. Neville-NeilThe 1776617cf57SGeorge V. Neville-Neil.Fn inet6_rth_getaddr 1786617cf57SGeorge V. Neville-Neilfunction returns a pointer to an IPv6 address on success or 1796617cf57SGeorge V. Neville-Neil.Dv NULL 1806617cf57SGeorge V. Neville-Neilwhen an error has occurred. 1816617cf57SGeorge V. Neville-Neil.\" 182f789cb82SRuslan Ermilov.Sh EXAMPLES 183f789cb82SRuslan ErmilovRFC 3542 gives extensive examples in Section 21, Appendix B. 184f789cb82SRuslan Ermilov.Pp 185f789cb82SRuslan ErmilovKAME also provides examples in the advapitest directory of its kit. 186f789cb82SRuslan Ermilov.\" 1876617cf57SGeorge V. Neville-Neil.Sh DIAGNOSTICS 1886617cf57SGeorge V. Neville-NeilThe 1896617cf57SGeorge V. Neville-Neil.Fn inet6_rth_space 1906617cf57SGeorge V. Neville-Neiland 1916617cf57SGeorge V. Neville-Neil.Fn inet6_rth_getaddr 1926617cf57SGeorge V. Neville-Neilfunctions return 0 on errors. 1936617cf57SGeorge V. Neville-Neil.Pp 1946617cf57SGeorge V. Neville-NeilThe 1956617cf57SGeorge V. Neville-Neil.Fn inet6_rthdr_init 1966617cf57SGeorge V. Neville-Neilfunction returns 1976617cf57SGeorge V. Neville-Neil.Dv NULL 1986617cf57SGeorge V. Neville-Neilon error. 1996617cf57SGeorge V. Neville-NeilThe 2006617cf57SGeorge V. Neville-Neil.Fn inet6_rth_add 2016617cf57SGeorge V. Neville-Neiland 2026617cf57SGeorge V. Neville-Neil.Fn inet6_rth_reverse 2036617cf57SGeorge V. Neville-Neilfunctions return 0 on success, or \-1 upon an error. 2046617cf57SGeorge V. Neville-Neil.\" 2056617cf57SGeorge V. Neville-Neil.Sh SEE ALSO 2066617cf57SGeorge V. Neville-Neil.Rs 2076617cf57SGeorge V. Neville-Neil.%A W. Stevens 2086617cf57SGeorge V. Neville-Neil.%A M. Thomas 2096617cf57SGeorge V. Neville-Neil.%A E. Nordmark 2106617cf57SGeorge V. Neville-Neil.%A T. Jinmei 2116617cf57SGeorge V. Neville-Neil.%T "Advanced Sockets API for IPv6" 2126617cf57SGeorge V. Neville-Neil.%N RFC 3542 2136617cf57SGeorge V. Neville-Neil.%D May 2003 2146617cf57SGeorge V. Neville-Neil.Re 2156617cf57SGeorge V. Neville-Neil.Rs 2166617cf57SGeorge V. Neville-Neil.%A S. Deering 2176617cf57SGeorge V. Neville-Neil.%A R. Hinden 2186617cf57SGeorge V. Neville-Neil.%T "Internet Protocol, Version 6 (IPv6) Specification" 2196617cf57SGeorge V. Neville-Neil.%N RFC2460 2206617cf57SGeorge V. Neville-Neil.%D December 1998 2216617cf57SGeorge V. Neville-Neil.Re 2226617cf57SGeorge V. Neville-Neil.Sh HISTORY 2236617cf57SGeorge V. Neville-NeilThe implementation first appeared in KAME advanced networking kit. 224