[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/net/inet6_opt_init.3

Version: -  FREEBSD  -  FREEBSD10  -  FREEBSD9  -  FREEBSD92  -  FREEBSD91  -  FREEBSD90  -  FREEBSD8  -  FREEBSD82  -  FREEBSD81  -  FREEBSD80  -  FREEBSD7  -  FREEBSD74  -  FREEBSD73  -  FREEBSD72  -  FREEBSD71  -  FREEBSD70  -  FREEBSD6  -  FREEBSD64  -  FREEBSD63  -  FREEBSD62  -  FREEBSD61  -  FREEBSD60  -  FREEBSD5  -  FREEBSD55  -  FREEBSD54  -  FREEBSD53  -  FREEBSD52  -  FREEBSD51  -  FREEBSD50  -  FREEBSD4  -  FREEBSD3  -  FREEBSD22  -  cheribsd  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1  -  FREEBSD-LIBC  -  FREEBSD8-LIBC  -  FREEBSD7-LIBC  -  FREEBSD6-LIBC  -  GLIBC27 
SearchContext: -  none  -  3  -  10 

    1 .\"     $KAME: inet6_opt_init.3,v 1.7 2004/12/27 05:08:23 itojun Exp $
    2 .\"
    3 .\" Copyright (C) 2004 WIDE Project.
    4 .\" All rights reserved.
    5 .\"
    6 .\" Redistribution and use in source and binary forms, with or without
    7 .\" modification, are permitted provided that the following conditions
    8 .\" are met:
    9 .\" 1. Redistributions of source code must retain the above copyright
   10 .\"    notice, this list of conditions and the following disclaimer.
   11 .\" 2. Redistributions in binary form must reproduce the above copyright
   12 .\"    notice, this list of conditions and the following disclaimer in the
   13 .\"    documentation and/or other materials provided with the distribution.
   14 .\" 3. Neither the name of the project nor the names of its contributors
   15 .\"    may be used to endorse or promote products derived from this software
   16 .\"    without specific prior written permission.
   17 .\"
   18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
   19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
   22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
   24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   28 .\" SUCH DAMAGE.
   29 .\"
   30 .\" $FreeBSD: stable/8/lib/libc/net/inet6_opt_init.3 152717 2005-11-23 16:07:54Z ru $
   31 .\"
   32 .Dd December 23, 2004
   33 .Dt INET6_OPT_INIT 3
   34 .Os
   35 .\"
   36 .Sh NAME
   37 .Nm inet6_opt_init ,
   38 .Nm inet6_opt_append ,
   39 .Nm inet6_opt_finish ,
   40 .Nm inet6_opt_set_val ,
   41 .Nm inet6_opt_next ,
   42 .Nm inet6_opt_find ,
   43 .Nm inet6_opt_get_val
   44 .Nd IPv6 Hop-by-Hop and Destination Options manipulation
   45 .\"
   46 .Sh SYNOPSIS
   47 .In netinet/in.h
   48 .Ft "int"
   49 .Fn inet6_opt_init "void *extbuf" "socklen_t extlen"
   50 .Ft "int"
   51 .Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp"
   52 .Ft "int"
   53 .Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset"
   54 .Ft "int"
   55 .Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen"
   56 .Ft "int"
   57 .Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp"
   58 .Ft "int"
   59 .Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp"
   60 .Ft "int"
   61 .Fn inet6_opt_get_val "void *databuf" "int offset" "void *val" "socklen_t vallen"
   62 .\"
   63 .Sh DESCRIPTION
   64 Building and parsing the Hop-by-Hop and Destination options is
   65 complicated.
   66 The advanced sockets API defines a set of functions to
   67 help applications create and manipulate Hop-by-Hop and Destination
   68 options.
   69 This man page describes the functions specified in
   70 IETF Draft RFC3542.
   71 These functions use the
   72 formatting rules specified in Appendix B in RFC2460, i.e., that the
   73 largest field is placed last in the option.
   74 The function prototypes
   75 for these functions are all contained in the
   76 .In netinet/in.h
   77 header file.
   78 .\"
   79 .Ss inet6_opt_init
   80 The
   81 .Fn inet6_opt_init
   82 function
   83 returns the number of bytes needed for an empty
   84 extension header, one without any options.
   85 If the
   86 .Fa extbuf
   87 argument points to a valid section of memory
   88 then the
   89 .Fn inet6_opt_init
   90 function also initializes the extension header's length field.
   91 When attempting to initialize an extension buffer passed in the
   92 .Fa extbuf
   93 argument,
   94 .Fa extlen
   95 must be a positive multiple of 8 or else the function fails and
   96 returns \-1 to the caller.
   97 .\"
   98 .Ss inet6_opt_append
   99 The
  100 .Fn inet6_opt_append
  101 function can perform two different jobs.
  102 When a valid
  103 .Fa extbuf
  104 argument is supplied it appends an option to the extension buffer and
  105 returns the updated total length as well as a pointer to the newly
  106 created option in
  107 .Fa databufp .
  108 If the value
  109 of
  110 .Fa extbuf
  111 is
  112 .Dv NULL
  113 then the
  114 .Fn inet6_opt_append
  115 function only reports what the total length would
  116 be if the option were actually appended.
  117 The
  118 .Fa len
  119 and
  120 .Fa align
  121 arguments specify the length of the option and the required data
  122 alignment which must be used when appending the option.
  123 The
  124 .Fa offset
  125 argument should be the length returned by the
  126 .Fn inet6_opt_init
  127 function or a previous call to
  128 .Fn inet6_opt_append .
  129 .Pp
  130 The
  131 .Fa type
  132 argument is the 8-bit option type.
  133 .Pp
  134 After
  135 .Fn inet6_opt_append
  136 has been called, the application can use the buffer pointed to by
  137 .Fa databufp
  138 directly, or use
  139 .Fn inet6_opt_set_val
  140 to specify the data to be contained in the option.
  141 .Pp
  142 Option types of
  143 .Li 0
  144 and
  145 .Li 1
  146 are reserved for the
  147 .Li Pad1
  148 and
  149 .Li PadN
  150 options.
  151 All other values from 2 through 255 may be used by applications.
  152 .Pp
  153 The length of the option data is contained in an 8-bit value and so
  154 may contain any value from 0 through 255.
  155 .Pp
  156 The
  157 .Fa align
  158 parameter must have a value of 1, 2, 4, or 8 and cannot exceed the
  159 value of
  160 .Fa len .
  161 The alignment values represent no alignment, 16 bit, 32 bit and 64 bit
  162 alignments, respectively.
  163 .\"
  164 .Ss inet6_opt_finish
  165 The
  166 .Fn inet6_opt_finish
  167 function
  168 calculates the final padding necessary to make the extension header a
  169 multiple of 8 bytes, as required by the IPv6 extension header
  170 specification, and returns the extension header's updated total
  171 length.
  172 The
  173 .Fa offset
  174 argument should be the length returned by
  175 .Fn inet6_opt_init
  176 or
  177 .Fn inet6_opt_append .
  178 When
  179 .Fa extbuf
  180 is not
  181 .Dv NULL
  182 the function also sets up the appropriate padding bytes by inserting a
  183 Pad1 or PadN option of the proper length.
  184 .Pp
  185 If the extension header is too small to contain the proper padding
  186 then an error of \-1 is returned to the caller.
  187 .\"
  188 .Ss inet6_opt_set_val
  189 The
  190 .Fn inet6_opt_set_val
  191 function inserts data items of various sizes into the data portion of
  192 the option.
  193 The
  194 .Fa databuf
  195 argument is a pointer to memory that was returned by the
  196 .Fn inet6_opt_append
  197 call and the
  198 .Fa offset
  199 argument specifies where the option should be placed in the
  200 data buffer.
  201 The
  202 .Fa val
  203 argument points to an area of memory containing the data to be
  204 inserted into the extension header, and the
  205 .Fa vallen
  206 argument indicates how much data to copy.
  207 .Pp
  208 The caller should ensure that each field is aligned on its natural
  209 boundaries as described in Appendix B of RFC2460.
  210 .Pp
  211 The function returns the offset for the next field which is calculated as
  212 .Fa offset
  213 +
  214 .Fa vallen
  215 and is used when composing options with multiple fields.
  216 .\"
  217 .Ss inet6_opt_next
  218 The
  219 .Fn inet6_opt_next
  220 function parses received extension headers.
  221 The
  222 .Fa extbuf
  223 and
  224 .Fa extlen
  225 arguments specify the location and length of the extension header
  226 being parsed.
  227 The
  228 .Fa offset
  229 argument should either be zero, for the first option, or the length value
  230 returned by a previous call to
  231 .Fn inet6_opt_next
  232 or
  233 .Fn inet6_opt_find .
  234 The return value specifies the position where to continue scanning the
  235 extension buffer.
  236 The option is returned in the arguments
  237 .Fa typep , lenp ,
  238 and
  239 .Fa databufp ,
  240 which
  241 point to the 8-bit option type, the 8-bit option length and the option
  242 data, respectively.
  243 This function does not return any PAD1 or PADN options.
  244 When an error occurs or there are no more options, the return
  245 value is \-1.
  246 .\"
  247 .Ss inet6_opt_find
  248 The
  249 .Fn inet6_opt_find
  250 function searches the extension buffer for a particular option type,
  251 passed in through the
  252 .Fa type
  253 argument.
  254 If the option is found then the
  255 .Fa lenp
  256 and
  257 .Fa databufp
  258 arguments are updated to point to the option's length and data,
  259 respectively.
  260 The
  261 .Fa extbuf
  262 and
  263 .Fa extlen
  264 arguments
  265 must point to a valid extension buffer and give its length.
  266 The
  267 .Fa offset
  268 argument can be used to search from a location anywhere in the
  269 extension header.
  270 .Ss inet6_opt_get_val
  271 The
  272 .Fn inet6_opt_get_val
  273 function extracts data items of various sizes in the data portion of
  274 the option.
  275 The
  276 .Fa databuf
  277 is a pointer returned by the
  278 .Fn inet6_opt_next
  279 or
  280 .Fn inet6_opt_find
  281 functions.
  282 The
  283 .Fa val
  284 argument points where the data will be extracted.
  285 The
  286 .Fa offset
  287 argument specifies from where in the data portion of the option the
  288 value should be extracted; the first byte of option data is specified
  289 by an offset of zero.
  290 .Pp
  291 It is expected that each field is aligned on its natural boundaries as
  292 described in Appendix B of RFC2460.
  293 .Pp
  294 The function returns the offset for the next field
  295 by calculating
  296 .Fa offset
  297 +
  298 .Fa vallen
  299 which can be used when extracting option content with multiple fields.
  300 Robust receivers must verify alignment before calling this function.
  301 .\"
  302 .Sh RETURN VALUES
  303 All the functions return
  304 \-1
  305 on an error.
  306 .\"
  307 .Sh EXAMPLES
  308 RFC3542 gives comprehensive examples in Section 23.
  309 .Pp
  310 KAME also provides examples in the
  311 .Pa advapitest
  312 directory of its kit.
  313 .\"
  314 .Sh SEE ALSO
  315 .Rs
  316 .%A W. Stevens
  317 .%A M. Thomas
  318 .%A E. Nordmark
  319 .%A T. Jinmei
  320 .%T "Advanced Sockets API for IPv6"
  321 .%N RFC3542
  322 .%D October 2002
  323 .Re
  324 .Rs
  325 .%A S. Deering
  326 .%A R. Hinden
  327 .%T "Internet Protocol, Version 6 (IPv6) Specification"
  328 .%N RFC2460
  329 .%D December 1998
  330 .Re
  331 .Sh STANDARDS
  332 The functions are documented in
  333 .Dq Advanced Sockets API for IPv6
  334 .Pq RFC3542 .
  335 .\"
  336 .Sh HISTORY
  337 The implementation first appeared in KAME advanced networking kit.

Cache object: ba8143ea7eac07c4a4fcf8bd0bdd9c47


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.