gen.subproj/inet6_option_space.3

   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_option_space.3,v 1.3 2005/01/19 00:30:03 majka Exp $
  33 .\" $FreeBSD: src/lib/libc/net/inet6_option_space.3,v 1.1.2.5 2001/08/17 15:42:38 ru Exp $
  34 .\"
  35 .Dd December 10, 1999
  36 .Dt INET6_OPTION_SPACE 3
  37 .Os
  38 .\"
  39 .Sh NAME
  40 .Nm inet6_option_space ,
  41 .Nm inet6_option_init ,
  42 .Nm inet6_option_append ,
  43 .Nm inet6_option_alloc ,
  44 .Nm inet6_option_next ,
  45 .Nm inet6_option_find
  46 .Nd IPv6 Hop-by-Hop and Destination Options manipulation
  47 .\"
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .Fd #include <sys/types.h>
  52 .Fd #include <netinet/in.h>
  53 .Ft "int"
  54 .Fn inet6_option_space "int nbytes"
  55 .Ft "int"
  56 .Fn inet6_option_init "void *bp" "struct cmsghdr **cmsgp" "int type"
  57 .Ft "int"
  58 .Fn inet6_option_append "struct cmsghdr *cmsg" "const u_int8_t *typep" "int multx" "int plusy"
  59 .Ft "u_int8_t *"
  60 .Fn inet6_option_alloc "struct cmsghdr *cmsg" "int datalen" "int multx" "int plusy"
  61 .Ft "int"
  62 .Fn inet6_option_next "const struct cmsghdr *cmsg" "u_int8_t **tptrp"
  63 .Ft "int"
  64 .Fn inet6_option_find "const struct cmsghdr *cmsg" "u_int8_t **tptrp" "int type"
  65 .\"
  66 .Sh DESCRIPTION
  67 .\"
  68 Building and parsing the Hop-by-Hop and Destination options is
  69 complicated due to alignment constranints, padding and
  70 ancillary data manipulation.
  71 RFC2292 defines a set of functions to help the application.
  72 The function prototypes for
  73 these functions are all in the
  74 .Aq Li netinet/in.h
  75 header.
  76 .Pp
  77 The full description of these functions is available in RFC2292.
  78 .\"
  79 .Sh DIAGNOSTICS
  80 .Fn inet6_option_init
  81 and
  82 .Fn inet6_option_append
  83 return
  84 .Li 0
  85 on success or
  86 .Li -1
  87 on an error.
  88 .Pp
  89 .Fn inet6_option_alloc
  90 returns
  91 .Dv NULL
  92 on an error.
  93 .Pp
  94 On errors,
  95 .Fn inet6_option_next
  96 and
  97 .Fn inet6_option_find
  98 return
  99 .Li -1
 100 setting
 101 .Fa *tptrp
 102 to non
 103 .Dv NULL
 104 value.
 105 .\"
 106 .Sh EXAMPLES
 107 RFC2292 gives comprehensive examples in chapter 6.
 108 .\"
 109 .Sh SEE ALSO
 110 .Rs
 111 .%A W. Stevens
 112 .%A M. Thomas
 113 .%T "Advanced Sockets API for IPv6"
 114 .%N RFC2292
 115 .%D February 1998
 116 .Re
 117 .Rs
 118 .%A S. Deering
 119 .%A R. Hinden
 120 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 121 .%N RFC2460
 122 .%D December 1998
 123 .Re
 124 .\"
 125 .Sh HISTORY
 126 The implementation first appeared in KAME advanced networking kit.
 127 .\"
 128 .Sh STANDARDS
 129 The functions
 130 are documented in
 131 .Dq Advanced Sockets API for IPv6
 132 (RFC2292).
 133 .\"
 134 .Sh BUGS