1.\" $NetBSD: inet6_rthdr_space.3,v 1.9 2003/05/03 19:11:31 wiz Exp $ 2.\" $KAME: inet6_rthdr_space.3,v 1.8 2000/05/17 14:30:15 itojun Exp $ 3.\" 4.\" Copyright (c) 1983, 1987, 1991, 1993 5.\" The Regents of the University of California. 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. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.Dd December 10, 1999 36.Dt INET6_RTHDR_SPACE 3 37.Os 38.\" 39.Sh NAME 40.Nm inet6_rthdr_space , 41.Nm inet6_rthdr_init , 42.Nm inet6_rthdr_add , 43.Nm inet6_rthdr_lasthop , 44.Nm inet6_rthdr_reverse , 45.Nm inet6_rthdr_segments , 46.Nm inet6_rthdr_getaddr , 47.Nm inet6_rthdr_getflags 48.Nd IPv6 Routing Header Options manipulation 49.\" 50.Sh SYNOPSIS 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 70RFC2292 IPv6 advanced API defines eight 71functions that the application calls to build and examine a Routing 72header. 73Four functions build a Routing header: 74.Bl -hang 75.It Fn inet6_rthdr_space 76return #bytes required for ancillary data 77.It Fn inet6_rthdr_init 78initialize ancillary data for Routing header 79.It Fn inet6_rthdr_add 80add IPv6 address \*[Am] flags to Routing header 81.It Fn inet6_rthdr_lasthop 82specify the flags for the final hop 83.El 84.Pp 85Four functions deal with a returned Routing header: 86.Bl -hang 87.It Fn inet6_rthdr_reverse 88reverse a Routing header 89.It Fn inet6_rthdr_segments 90return #segments in a Routing header 91.It Fn inet6_rthdr_getaddr 92fetch one address from a Routing header 93.It Fn inet6_rthdr_getflags 94fetch one flag from a Routing header 95.El 96.Pp 97The function prototypes for these functions are all in the 98.Aq Pa netinet/in.h 99header. 100.\" 101.Ss inet6_rthdr_space 102This function returns the number of bytes required to hold a Routing 103header of the specified 104.Fa type 105containing the specified number of 106.Fa segments 107.Pq addresses . 108For an IPv6 Type 0 Routing header, the number 109of segments must be between 1 and 23, inclusive. 110The return value 111includes the size of the cmsghdr structure that precedes the Routing 112header, and any required padding. 113.Pp 114If the return value is 0, then either the type of the Routing header 115is not supported by this implementation or the number of segments is 116invalid for this type of Routing header. 117.Pp 118Note: This function returns the size but does not allocate the space 119required for the ancillary data. 120This allows an application to 121allocate a larger buffer, if other ancillary data objects are 122desired, since all the ancillary data objects must be specified to 123.Xr sendmsg 2 124as a single 125.Li msg_control 126buffer. 127.\" 128.Ss inet6_rthdr_init 129This function initializes the buffer pointed to by 130.Fa bp 131to contain a 132.Li cmsghdr 133structure followed by a Routing header of the specified 134.Fa type . 135The 136.Li cmsg_len 137member of the 138.Li cmsghdr 139structure is initialized to the 140size of the structure plus the amount of space required by the 141Routing header. 142The 143.Li cmsg_level 144and 145.Li cmsg_type 146members are also initialized as required. 147.Pp 148The caller must allocate the buffer and its size can be determined by 149calling 150.Fn inet6_rthdr_space . 151.Pp 152Upon success the return value is the pointer to the 153.Li cmsghdr 154structure, and this is then used as the first argument to the next 155two functions. 156Upon an error the return value is 157.Dv NULL . 158.\" 159.Ss inet6_rthdr_add 160This function adds the address pointed to by 161.Fa addr 162to the end of the 163Routing header being constructed and sets the type of this hop to the 164value of 165.Fa flags . 166For an IPv6 Type 0 Routing header, 167.Fa flags 168must be 169either 170.Dv IPV6_RTHDR_LOOSE 171or 172.Dv IPV6_RTHDR_STRICT . 173.Pp 174If successful, the 175.Li cmsg_len 176member of the 177.Li cmsghdr 178structure is 179updated to account for the new address in the Routing header and the 180return value of the function is 0. 181Upon an error the return value of 182the function is -1. 183.\" 184.Ss inet6_rthdr_lasthop 185This function specifies the Strict/Loose flag for the final hop of a 186Routing header. 187For an IPv6 Type 0 Routing header, 188.Fa flags 189must be either 190.Dv IPV6_RTHDR_LOOSE 191or 192.Dv IPV6_RTHDR_STRICT . 193.Pp 194The return value of the function is 0 upon success, or -1 upon an error. 195.Pp 196Notice that a Routing header specifying 197.Li N 198intermediate nodes requires 199.Li N+1 200Strict/Loose flags. 201This requires 202.Li N 203calls to 204.Fn inet6_rthdr_add 205followed by one call to 206.Fn inet6_rthdr_lasthop . 207.\" 208.Ss inet6_rthdr_reverse 209This function takes a Routing header that was received as ancillary 210data 211.Po 212pointed to by the first argument, 213.Fa in 214.Pc 215and writes a new Routing 216header that sends datagrams along the reverse of that route. 217Both 218arguments are allowed to point to the same buffer 219.Pq that is, the reversal can occur in place . 220.Pp 221The return value of the function is 0 on success, or -1 upon an 222error. 223.\" 224.Ss inet6_rthdr_segments 225This function returns the number of segments 226.Pq addresses 227contained in 228the Routing header described by 229.Fa cmsg . 230On success the return value is 231between 1 and 23, inclusive. 232The return value of the function is -1 upon an error. 233.\" 234.Ss inet6_rthdr_getaddr 235This function returns a pointer to the IPv6 address specified by 236.Fa index 237.Po 238which must have a value between 1 and the value returned by 239.Fn inet6_rthdr_segments 240.Pc 241in the Routing header described by 242.Fa cmsg . 243An 244application should first call 245.Fn inet6_rthdr_segments 246to obtain the number of segments in the Routing header. 247.Pp 248Upon an error the return value of the function is 249.Dv NULL . 250.\" 251.Ss inet6_rthdr_getflags 252This function returns the flags value specified by 253.Fa index 254.Po 255which must 256have a value between 0 and the value returned by 257.Fn inet6_rthdr_segments 258.Pc 259in the Routing header described by 260.Fa cmsg . 261For an IPv6 Type 0 Routing header the return value will be either 262.Dv IPV6_RTHDR_LOOSE 263or 264.Dv IPV6_RTHDR_STRICT . 265.Pp 266Upon an error the return value of the function is -1. 267.Pp 268Note: Addresses are indexed starting at 1, and flags starting at 0, 269to maintain consistency with the terminology and figures in RFC2460. 270.\" 271.Sh EXAMPLES 272RFC2292 gives comprehensive examples in chapter 8. 273.\" 274.Sh DIAGNOSTICS 275.Fn inet6_rthdr_space 276returns 0 on errors. 277.Pp 278.Fn inet6_rthdr_add , 279.Fn inet6_rthdr_lasthop 280and 281.Fn inet6_rthdr_reverse 282return 0 on success, and returns -1 on error. 283.Pp 284.Fn inet6_rthdr_init 285and 286.Fn inet6_rthdr_getaddr 287return 288.Dv NULL 289on error. 290.Pp 291.Fn inet6_rthdr_segments 292and 293.Fn inet6_rthdr_getflags 294return -1 on error. 295.\" 296.Sh SEE ALSO 297.Rs 298.%A W. Stevens 299.%A M. Thomas 300.%T "Advanced Sockets API for IPv6" 301.%N RFC2292 302.%D February 1998 303.Re 304.Rs 305.%A S. Deering 306.%A R. Hinden 307.%T "Internet Protocol, Version 6 (IPv6) Specification" 308.%N RFC2460 309.%D December 1998 310.Re 311.\" 312.Sh STANDARDS 313The functions 314are documented in 315.Dq Advanced Sockets API for IPv6 316.Pq RFC2292 . 317.\" 318.Sh HISTORY 319The implementation first appeared in KAME advanced networking kit. 320.\" 321.Sh BUGS 322The text was shamelessly copied from RFC2292. 323.Pp 324.Fn inet6_rthdr_reverse 325is not implemented yet. 326