1.\" Copyright (c) 1983, 1987, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University 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 REGENTS 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 REGENTS 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.\" $Id: inet6_rthdr_space.3,v 1.5 2000/02/05 13:19:07 jinmei Exp $ 33.\" $FreeBSD$ 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 LIBRARY 51.Lb libc 52.Sh SYNOPSIS 53.In sys/types.h 54.In netinet/in.h 55.Ft size_t 56.Fn inet6_rthdr_space "int type" "int segments" 57.Ft "struct cmsghdr *" 58.Fn inet6_rthdr_init "void *bp" "int type" 59.Ft int 60.Fn inet6_rthdr_add "struct cmsghdr *cmsg" "const struct in6_addr *addr" "unsigned int flags" 61.Ft int 62.Fn inet6_rthdr_lasthop "struct cmsghdr *cmsg" "unsigned int flags" 63.Ft int 64.Fn inet6_rthdr_reverse "const struct cmsghdr *in" "struct cmsghdr *out" 65.Ft int 66.Fn inet6_rthdr_segments "const struct cmsghdr *cmsg" 67.Ft "struct in6_addr *" 68.Fn inet6_rthdr_getaddr "struct cmsghdr *cmsg" "int index" 69.Ft int 70.Fn inet6_rthdr_getflags "const struct cmsghdr *cmsg" "int index" 71.\" 72.Sh DESCRIPTION 73RFC2292 IPv6 advanced API defines eight 74functions that the application calls to build and examine a Routing 75header. 76Four functions build a Routing header: 77.Bl -hang 78.It Fn inet6_rthdr_space 79return #bytes required for ancillary data 80.It Fn inet6_rthdr_init 81initialize ancillary data for Routing header 82.It Fn inet6_rthdr_add 83add IPv6 address & flags to Routing header 84.It Fn inet6_rthdr_lasthop 85specify the flags for the final hop 86.El 87.Pp 88Four functions deal with a returned Routing header: 89.Bl -hang 90.It Fn inet6_rthdr_reverse 91reverse a Routing header 92.It Fn inet6_rthdr_segments 93return #segments in a Routing header 94.It Fn inet6_rthdr_getaddr 95fetch one address from a Routing header 96.It Fn inet6_rthdr_getflags 97fetch one flag from a Routing header 98.El 99.Pp 100The function prototypes for these functions are all in the 101.In netinet/in.h 102header. 103.\" 104.Ss inet6_rthdr_space 105This function returns the number of bytes required to hold a Routing 106header of the specified 107.Fa type 108containing the specified number of 109.Fa segments 110(addresses). 111For an IPv6 Type 0 Routing header, the number 112of segments must be between 1 and 23, inclusive. 113The return value 114includes the size of the cmsghdr structure that precedes the Routing 115header, and any required padding. 116.Pp 117If the return value is 0, then either the type of the Routing header 118is not supported by this implementation or the number of segments is 119invalid for this type of Routing header. 120.Pp 121Note: This function returns the size but does not allocate the space 122required for the ancillary data. 123This allows an application to 124allocate a larger buffer, if other ancillary data objects are 125desired, since all the ancillary data objects must be specified to 126.Xr sendmsg 2 127as a single 128.Li msg_control 129buffer. 130.\" 131.Ss inet6_rthdr_init 132This function initializes the buffer pointed to by 133.Fa bp 134to contain a 135.Li cmsghdr 136structure followed by a Routing header of the specified 137.Fa type . 138The 139.Li cmsg_len 140member of the 141.Li cmsghdr 142structure is initialized to the 143size of the structure plus the amount of space required by the 144Routing header. 145The 146.Li cmsg_level 147and 148.Li cmsg_type 149members are also initialized as required. 150.Pp 151The caller must allocate the buffer and its size can be determined by 152calling 153.Fn inet6_rthdr_space . 154.Pp 155Upon success the return value is the pointer to the 156.Li cmsghdr 157structure, and this is then used as the first argument to the next 158two functions. 159Upon an error the return value is 160.Dv NULL . 161.\" 162.Ss inet6_rthdr_add 163This function adds the address pointed to by 164.Fa addr 165to the end of the 166Routing header being constructed and sets the type of this hop to the 167value of 168.Fa flags . 169For an IPv6 Type 0 Routing header, 170.Fa flags 171must be 172either 173.Dv IPV6_RTHDR_LOOSE 174or 175.Dv IPV6_RTHDR_STRICT . 176.Pp 177If successful, the 178.Li cmsg_len 179member of the 180.Li cmsghdr 181structure is 182updated to account for the new address in the Routing header and the 183return value of the function is 0. 184Upon an error the return value of 185the function is -1. 186.\" 187.Ss inet6_rthdr_lasthop 188This function specifies the Strict/Loose flag for the final hop of a 189Routing header. 190For an IPv6 Type 0 Routing header, 191.Fa flags 192must be either 193.Dv IPV6_RTHDR_LOOSE 194or 195.Dv IPV6_RTHDR_STRICT . 196.Pp 197The return value of the function is 0 upon success, or -1 upon an error. 198.Pp 199Notice that a Routing header specifying 200.Li N 201intermediate nodes requires 202.Li N+1 203Strict/Loose flags. 204This requires 205.Li N 206calls to 207.Fn inet6_rthdr_add 208followed by one call to 209.Fn inet6_rthdr_lasthop . 210.\" 211.Ss inet6_rthdr_reverse 212This function is not yet implemented. 213When implemented, this should behave as follows. 214.Pp 215This function takes a Routing header that was received as ancillary 216data 217(pointed to by the first argument, 218.Fa in ) 219and writes a new Routing 220header that sends datagrams along the reverse of that route. 221Both 222arguments are allowed to point to the same buffer 223(that is, the reversal can occur in place). 224.Pp 225The return value of the function is 0 on success, or -1 upon an 226error. 227.\" 228.Ss inet6_rthdr_segments 229This function returns the number of segments 230(addresses) 231contained in 232the Routing header described by 233.Fa cmsg . 234On success the return value is 235between 1 and 23, inclusive. 236The return value of the function is -1 upon an error. 237.\" 238.Ss inet6_rthdr_getaddr 239This function returns a pointer to the IPv6 address specified by 240.Fa index 241(which must have a value between 1 and the value returned by 242.Fn inet6_rthdr_segments ) 243in the Routing header described by 244.Fa cmsg . 245An 246application should first call 247.Fn inet6_rthdr_segments 248to obtain the number of segments in the Routing header. 249.Pp 250Upon an error the return value of the function is 251.Dv NULL . 252.\" 253.Ss inet6_rthdr_getflags 254This function returns the flags value specified by 255.Fa index 256(which must 257have a value between 0 and the value returned by 258.Fn inet6_rthdr_segments ) 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 DIAGNOSTICS 272The 273.Fn inet6_rthdr_space 274function 275returns 0 on errors. 276.Pp 277The 278.Fn inet6_rthdr_add , 279.Fn inet6_rthdr_lasthop 280and 281.Fn inet6_rthdr_reverse 282functions 283return 0 on success, and returns -1 on error. 284.Pp 285The 286.Fn inet6_rthdr_init 287and 288.Fn inet6_rthdr_getaddr 289functions 290return 291.Dv NULL 292on error. 293.Pp 294The 295.Fn inet6_rthdr_segments 296and 297.Fn inet6_rthdr_getflags 298functions 299return -1 on error. 300.\" 301.Sh EXAMPLES 302RFC2292 gives comprehensive examples in chapter 8. 303.\" 304.Sh SEE ALSO 305.Rs 306.%A W. Stevens 307.%A M. Thomas 308.%T "Advanced Sockets API for IPv6" 309.%N RFC2292 310.%D February 1998 311.Re 312.Rs 313.%A S. Deering 314.%A R. Hinden 315.%T "Internet Protocol, Version 6 (IPv6) Specification" 316.%N RFC2460 317.%D December 1998 318.Re 319.\" 320.Sh HISTORY 321The implementation first appeared in KAME advanced networking kit. 322.\" 323.Sh STANDARDS 324The functions 325are documented in 326.Dq Advanced Sockets API for IPv6 327(RFC2292). 328.\" 329.Sh BUGS 330The text was shamelessly copied from RFC2292. 331.Pp 332The 333.Fn inet6_rthdr_reverse 334function 335is not implemented yet. 336