INET6_RTHDR_SPACE(3) OpenBSD Programmer's Manual INET6_RTHDR_SPACE(3)NAME
inet6_rthdr_space, inet6_rthdr_init, inet6_rthdr_add,
inet6_rthdr_lasthop, inet6_rthdr_reverse, inet6_rthdr_segments,
inet6_rthdr_getaddr, inet6_rthdr_getflags - IPv6 Routing Header Options
Manipulation
SYNOPSIS
#include <sys/types.h>
#include <netinet/in.h>
size_t
inet6_rthdr_space(int type, int segments);
struct cmsghdr *
inet6_rthdr_init(void *bp, int type);
int
inet6_rthdr_add(struct cmsghdr *cmsg, const struct in6_addr
*addr, unsigned int flags);
int
inet6_rthdr_lasthop(struct cmsghdr *cmsg, unsigned int flags);
int
inet6_rthdr_reverse(const struct cmsghdr *in, struct cmsghdr *out);
int
inet6_rthdr_segments(const struct cmsghdr *cmsg);
struct in6_addr *
inet6_rthdr_getaddr(struct cmsghdr *cmsg, int index);
int
inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index);
DESCRIPTION
Note: RFC 2292 has been superseded by RFC 3542. The use of functions
described in this page is deprecated. See inet6_rth_space(3).
The RFC 2292 IPv6 Advanced API defined eight functions for applications
to use for building and parsing routing headers. The eight functions are
split into two groups, the first of which builds the header and the
second of which can parse it. The function prototypes for these
functions are all in the <netinet/in.h> header. Although direct
manipulation of a routing header is possible, this set of APIs make it
unnecessary and such direct manipulation should be avoided so that
changes to the underlying structures do not break applications.
Please note that RFC 2292 uses the term ``segments'' instead of the term
``addresses'' but they are considered equivalent for this manual page.
inet6_rthdr_space
The inet6_rthdr_space() function returns the number of bytes required to
hold a routing header of the specified type and containing the specified
number of segments. Only one type is supported, IPV6_RTHDR_TYPE_0, and
it can hold from 1 to 23 segments. The return value includes the size of
the cmsghdr structure that precedes the routing header and any required
padding.
A return value of 0 indicates an error. Either the type was specified
incorrectly, or the number of segments was less than one or greater than
23.
Note: The inet6_rthdr_space() function only returns the size required by
the routing header and does not allocate memory for the caller.
inet6_rthdr_init
The inet6_rthdr_init() function initializes a buffer, pointed to by bp
with an appropriate cmsghdr structure followed by a routing header of the
specified type.
The caller must use the inet6_rthdr_space() function to determine the
size of the buffer, and then allocate that buffer before calling
inet6_rthdr_init().
The return value is a pointer to a cmsghdr structure, which is used as
the first argument to the inet6_rthdr_add() and inet6_rthdr_lasthop()
functions in order to construct the routing header. When an error occurs
the return value is NULL.
inet6_rthdr_add
The inet6_rthdr_add() function adds the IPv6 address pointed to by addr
to the end of the routing header being constructed and sets the type of
this address to the value of flags. The flags must be either
IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT indicating whether loose or strict
source routing is required.
When the function succeeds it returns 0, otherwise -1 is returned.
inet6_rthdr_lasthop
The inet6_rthdr_lasthop() function specifies the strict or loose flag for
the final hop of a routing header. The flags argument must be either
IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.
The return value of the function is 0 upon success, and -1 when an error
has occurred.
Please note that a routing header specifying N intermediate nodes
requires N+1 strict or loose flags meaning that inet6_rthdr_add() must be
called N times and then inet6_rthdr_lasthop() must be called once.
inet6_rthdr_reverse
This function was never implemented.
The following three functions provide an API for parsing a received
routing header:
inet6_rthdr_segments
The inet6_rthdr_segments() function returns the number of segments
contained in the routing header pointed to by the cmsg argument. On
success the return value is from 1 to 23. When an error occurs, -1 is
returned.
inet6_rthdr_getaddr
The inet6_rthdr_getaddr() function returns a pointer to the IPv6 address
specified by the index argument from the routing header pointed to by
cmsg. The index must be between 1 and the number returned by
inet6_rthdr_segments(), described above. An application must call
inet6_rthdr_segments() to obtain the number of segments in the routing
header.
If an error occurs, NULL is returned.
inet6_rthdr_getflags
The inet6_rthdr_getflags() function returns the flags value of the
segment specified by index of the routing header pointed to by cmsg. The
index argument must be between 0 and the value returned by
inet6_rthdr_segments(). The return value will be either IPV6_RTHDR_LOOSE
or IPV6_RTHDR_STRICT indicating whether loose or strict source routing
was requested for that segment.
When an error occurs, -1 is returned.
Note: Flags begin at index 0 while segments begin at index 1, to maintain
consistency with the terminology and figures in RFC 2460.
EXAMPLES
RFC 2292 gives comprehensive examples in chapter 8.
DIAGNOSTICS
The inet6_rthdr_space() function returns 0 when an error occurs.
The inet6_rthdr_add() and inet6_rthdr_lasthop() functions return 0 on
success, and -1 on error.
The inet6_rthdr_init() and inet6_rthdr_getaddr() functions return NULL on
error.
The inet6_rthdr_segments() and inet6_rthdr_getflags() functions return -1
on error.
SEE ALSOinet6(4), ip6(4)
W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC 2292,
February 1998.
S. Deering and R. Hinden, Internet Protocol, Version 6 (IPv6)
Specification, RFC 2460, December 1998.
HISTORY
This implementation first appeared in the KAME advanced networking kit.
BUGS
The inet6_rthdr_reverse() function was never implemented.
OpenBSD 4.9 May 31, 2007 OpenBSD 4.9