Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
INET6_RTHDR_SPACE(3)	 BSD Library Functions 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

LIBRARY
     Standard C	Library	(libc, -lc)

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
     RFC2292 IPv6 advanced API defines eight functions that the	application
     calls to build and	examine	a Routing header.  Four	functions build	a
     Routing header:

     inet6_rthdr_space() return	#bytes required	for ancillary data

     inet6_rthdr_init()	initialize ancillary data for Routing header

     inet6_rthdr_add() add IPv6	address	& flags	to Routing header

     inet6_rthdr_lasthop() specify the flags for the final hop

     Four functions deal with a	returned Routing header:

     inet6_rthdr_reverse() reverse a Routing header

     inet6_rthdr_segments() return #segments in	a Routing header

     inet6_rthdr_getaddr() fetch one address from a Routing header

     inet6_rthdr_getflags() fetch one flag from	a Routing header

     The function prototypes for these functions are all in the	<netinet/in.h>
     header.

   inet6_rthdr_space
     This function returns the number of bytes required	to hold	a Routing
     header of the specified type containing the specified number of segments
     (addresses).  For an IPv6 Type 0 Routing header, the number of segments
     must be between 1 and 23, inclusive.  The return value includes the size
     of	the cmsghdr structure that precedes the	Routing	header,	and any	re-
     quired padding.

     If	the return value is 0, then either the type of the Routing header is
     not supported by this implementation or the number	of segments is invalid
     for this type of Routing header.

     Note: This	function returns the size but does not allocate	the space re-
     quired for	the ancillary data.  This allows an application	to allocate a
     larger buffer, if other ancillary data objects are	desired, since all the
     ancillary data objects must be specified to sendmsg(2) as a single
     msg_control buffer.

   inet6_rthdr_init
     This function initializes the buffer pointed to by	bp to contain a
     cmsghdr structure followed	by a Routing header of the specified type.
     The cmsg_len member of the	cmsghdr	structure is initialized to the	size
     of	the structure plus the amount of space required	by the Routing header.
     The cmsg_level and	cmsg_type members are also initialized as required.

     The caller	must allocate the buffer and its size can be determined	by
     calling inet6_rthdr_space().

     Upon success the return value is the pointer to the cmsghdr structure,
     and this is then used as the first	argument to the	next two functions.
     Upon an error the return value is NULL.

   inet6_rthdr_add
     This function adds	the address pointed to by addr to the end of the Rout-
     ing header	being constructed and sets the type of this hop	to the value
     of	flags.	For an IPv6 Type 0 Routing header, flags must be either
     IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.

     If	successful, the	cmsg_len member	of the cmsghdr structure is updated to
     account for the new address in the	Routing	header and the return value of
     the function is 0.	 Upon an error the return value	of the function	is -1.

   inet6_rthdr_lasthop
     This function specifies the Strict/Loose flag for the final hop of	a
     Routing header.  For an IPv6 Type 0 Routing header, flags must be either
     IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.

     The return	value of the function is 0 upon	success, or -1 upon an error.

     Notice that a Routing header specifying N intermediate nodes requires N+1
     Strict/Loose flags.  This requires	N calls	to inet6_rthdr_add() followed
     by	one call to inet6_rthdr_lasthop().

   inet6_rthdr_reverse
     This function is not yet implemented.  When implemented, this should be-
     have as follows.

     This function takes a Routing header that was received as ancillary data
     (pointed to by the	first argument,	in) and	writes a new Routing header
     that sends	datagrams along	the reverse of that route.  Both arguments are
     allowed to	point to the same buffer (that is, the reversal	can occur in
     place).

     The return	value of the function is 0 on success, or -1 upon an error.

   inet6_rthdr_segments
     This function returns the number of segments (addresses) contained	in the
     Routing header described by cmsg.	On success the return value is between
     1 and 23, inclusive.  The return value of the function is -1 upon an er-
     ror.

   inet6_rthdr_getaddr
     This function returns a pointer to	the IPv6 address specified by index
     (which must have a	value between 1	and the	value returned by
     inet6_rthdr_segments()) in	the Routing header described by	cmsg.  An ap-
     plication should first call inet6_rthdr_segments()	to obtain the number
     of	segments in the	Routing	header.

     Upon an error the return value of the function is NULL.

   inet6_rthdr_getflags
     This function returns the flags value specified by	index (which must have
     a value between 0 and the value returned by inet6_rthdr_segments()) in
     the Routing header	described by cmsg.  For	an IPv6	Type 0 Routing header
     the return	value will be either IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT.

     Upon an error the return value of the function is -1.

     Note: Addresses are indexed starting at 1,	and flags starting at 0, to
     maintain consistency with the terminology and figures in RFC2460.

DIAGNOSTICS
     inet6_rthdr_space() returns 0 on errors.

     inet6_rthdr_add(),	inet6_rthdr_lasthop() and inet6_rthdr_reverse()	return
     0 on success, and returns -1 on error.

     inet6_rthdr_init()	and inet6_rthdr_getaddr() return NULL on error.

     inet6_rthdr_segments() and	inet6_rthdr_getflags() return -1 on error.

EXAMPLES
     RFC2292 gives comprehensive examples in chapter 8.

SEE ALSO
     W.	Stevens	and M. Thomas, Advanced	Sockets	API for	IPv6, RFC2292,
     February 1998.

     S.	Deering	and R. Hinden, Internet	Protocol, Version 6 (IPv6)
     Specification, RFC2460, December 1998.

HISTORY
     The implementation	first appeared in KAME advanced	networking kit.

STANDARDS
     The functions are documented in "Advanced Sockets API for IPv6"
     (RFC2292).

BUGS
     The text was shamelessly copied from RFC2292.

     inet6_rthdr_reverse() is not implemented yet.

BSD			       December	10, 1999			   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | DIAGNOSTICS | EXAMPLES | SEE ALSO | HISTORY | STANDARDS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=inet6_rthdr_space&sektion=3&manpath=FreeBSD+4.9-RELEASE>

home | help