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