1.\" $KAME: inet6_rthdr_space.3,v 1.11 2005/01/05 03:00:44 itojun Exp $ 2.\" $FreeBSD: src/lib/libc/net/inet6_rthdr_space.3,v 1.14 2005/01/23 16:02:48 gnn Exp $ 3.\" $DragonFly: src/lib/libc/net/inet6_rthdr_space.3,v 1.5 2007/11/23 23:16:36 swildner Exp $ 4.\" 5.\" Copyright (C) 2004 WIDE Project. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the project nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd December 27, 2004 33.Dt INET6_RTHDR_SPACE 3 34.Os 35.\" 36.Sh NAME 37.Nm inet6_rthdr_space , 38.Nm inet6_rthdr_init , 39.Nm inet6_rthdr_add , 40.Nm inet6_rthdr_lasthop , 41.Nm inet6_rthdr_reverse , 42.Nm inet6_rthdr_segments , 43.Nm inet6_rthdr_getaddr , 44.Nm inet6_rthdr_getflags 45.Nd IPv6 Routing Header Options Manipulation 46.\" 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In sys/types.h 51.In netinet/in.h 52.Ft size_t 53.Fn inet6_rthdr_space "int type" "int segments" 54.Ft "struct cmsghdr *" 55.Fn inet6_rthdr_init "void *bp" "int type" 56.Ft int 57.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags" 58.Ft int 59.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags" 60.Ft int 61.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out" 62.Ft int 63.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg" 64.Ft "struct in6_addr *" 65.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index" 66.Ft int 67.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index" 68.\" 69.Sh DESCRIPTION 70.\"The RFC 2292 IPv6 Advanced API has been deprecated in favor of the 71.\"newer, RFC 3542 APIs. 72.\"On platforms that support it, currently only 73.\"FreeBSD, please use the newer API to manipulate routing header 74.\"options. 75.\".Pp 76The RFC 2292 IPv6 Advanced API defined eight functions for 77applications to use for building and parsing routing headers. 78The 79eight functions are split into two groups, the first of which builds 80the header and the second of which can parse it. 81The function prototypes for these functions are all in the 82.In netinet/in.h 83header. 84Although direct manipulation of a routing header is possible 85this set of APIs make it unnecessary and such direct manipulation 86should be avoided so that changes to the underlying structures do not 87break applications. 88.Pp 89Please note that RFC 2292 uses the term 90.Dq segments 91instead of the term 92.Dq addresses 93but they are considered equivalent for this manual page. 94.\" 95.Ss inet6_rthdr_space 96The 97.Fn inet6_rthdr_space 98function returns the number of bytes required to hold a routing header 99of the specified 100.Fa type 101and containing the specified number of 102.Fa segments . 103Only one 104.Fa type 105is supported, 106.Dv IPV6_RTHDR_TYPE_0 , 107and it can hold from 1 to 23 segments. 108The return value includes the 109size of the cmsghdr structure that precedes the routing header, and 110any required padding. 111.Pp 112A return value of 0 indicates an error. 113Either the type was specified 114incorrectly, or the number of segments was less than one or greater 115than 23. 116.Pp 117Note: The 118.Fn inet6_rthdr_space 119function only returns the size required by the routing header and does 120not allocate memory for the caller. 121.\" 122.Ss inet6_rthdr_init 123The 124.Fn inet6_rthdr_init 125function initializes a buffer, pointed to by 126.Fa bp 127with an appropriate 128.Li cmsghdr 129structure followed by a routing header of the specified 130.Fa type . 131.Pp 132The caller must use the 133.Fn inet6_rthdr_space 134function to determine the size of the buffer, and then allocate that 135buffer before calling 136.Fn inet6_rthdr_init . 137.Pp 138The return value is a pointer to a 139.Li cmsghdr 140structure, which is used as the first argument to the 141.Fn inet6_rthdr_add 142and 143.Fn inet6_rthdr_lasthop 144functions in order to construct the routing header. 145When an error occurs the return value is 146.Dv NULL . 147.\" 148.Ss inet6_rthdr_add 149The 150.Fn inet6_rthdr_add 151function adds the IPv6 address pointed to by 152.Fa addr 153to the end of the 154routing header being constructed and sets the type of this address to the 155value of 156.Fa flags . 157The 158.Fa flags 159must be either 160.Dv IPV6_RTHDR_LOOSE 161or 162.Dv IPV6_RTHDR_STRICT 163indicating whether loose or strict source routing is required. 164.Pp 165When the function succeeds it returns 0, otherwise \-1 is returned. 166.\" 167.Ss inet6_rthdr_lasthop 168The 169.Fn inet6_rthdr_lasthop 170function specifies the strict or loose flag for the final hop of a 171routing header. 172The 173.Fa flags 174must be either 175.Dv IPV6_RTHDR_LOOSE 176or 177.Dv IPV6_RTHDR_STRICT . 178.Pp 179The return value of the function is 0 upon success, and \-1 when an 180error has occurred. 181.Pp 182Please note that a routing header specifying 183.Li N 184intermediate nodes requires 185.Li N+1 186strict or loose flags meaning that 187.Fn inet6_rthdr_add 188must be called 189.Li N 190times and then 191.Fn inet6_rthdr_lasthop 192must be called once. 193.\" 194.Ss inet6_rthdr_reverse 195This function was never implemented. 196.Pp 197The following four functions provide an API for parsing a received 198routing header. 199.\" 200.Ss inet6_rthdr_segments 201The 202.Fn inet6_rthdr_segments 203function returns the number of segments contained in the Routing 204header pointed to by the 205.Fa cmsg 206argument. 207On success the return value is from 1 to 23. 208When an error occurs \-1 is returned. 209.\" 210.Ss inet6_rthdr_getaddr 211The 212.Fn inet6_rthdr_getaddr 213function returns a pointer to the IPv6 address specified by the 214.Fa index 215argument from the routing header pointed to by 216.Fa cmsg . 217The index must be between 1 and the number returned by 218.Fn inet6_rthdr_segments 219described above. 220An application must call 221.Fn inet6_rthdr_segments 222to obtain the number of segments in the routing header. 223.Pp 224If an error occurs the 225.Dv NULL 226is returned. 227.\" 228.Ss inet6_rthdr_getflags 229The 230.Fn inet6_rthdr_getflags 231function returns the flags value of the segment specified by 232.Fa index 233of the routing header pointed to by 234.Fa cmsg . 235The 236.Fa index 237argument must be between 0 and the value returned by 238.Fn inet6_rthdr_segments . 239The return value will be either 240.Dv IPV6_RTHDR_LOOSE 241or 242.Dv IPV6_RTHDR_STRICT 243indicating whether loose or strict source routing was requested for 244that segment. 245.Pp 246When an error occurs \-1 is returned. 247.Pp 248Note: Flags begin at index 0 while segments begin at index 1, to 249maintain consistency with the terminology and figures in RFC 2460. 250.\" 251.Sh EXAMPLES 252RFC 2292 gives comprehensive examples in chapter 8. 253.\" 254.Sh DIAGNOSTICS 255The 256.Fn inet6_rthdr_space 257function returns 0 when an error occurs. 258.Pp 259The 260.Fn inet6_rthdr_add , 261.Fn inet6_rthdr_lasthop 262functions return 0 on success, and \-1 on error. 263.Pp 264The 265.Fn inet6_rthdr_init 266and 267.Fn inet6_rthdr_getaddr 268functions 269return 270.Dv NULL 271on error. 272.Pp 273The 274.Fn inet6_rthdr_segments 275and 276.Fn inet6_rthdr_getflags 277functions return -1 on error. 278.\" 279.Sh SEE ALSO 280.Rs 281.%A W. Stevens 282.%A M. Thomas 283.%T "Advanced Sockets API for IPv6" 284.%N RFC 2292 285.%D February 1998 286.Re 287.Rs 288.%A S. Deering 289.%A R. Hinden 290.%T "Internet Protocol, Version 6 (IPv6) Specification" 291.%N RFC 2460 292.%D December 1998 293.Re 294.\" 295.Sh HISTORY 296The implementation first appeared in KAME advanced networking kit. 297.\" 298.Sh BUGS 299The 300.Fn inet6_rthdr_reverse 301function was never implemented. 302.\".Pp 303.\"This API is deprecated in favor of 304.\".Xr inet6_rth_space 3 305.\".Sh SEE ALSO 306.\".Xr inet6_rth_space 3 307