diff options
Diffstat (limited to 'lib/libc/net/inet6_opt_init.3')
| -rw-r--r-- | lib/libc/net/inet6_opt_init.3 | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/lib/libc/net/inet6_opt_init.3 b/lib/libc/net/inet6_opt_init.3 new file mode 100644 index 0000000..65af709 --- /dev/null +++ b/lib/libc/net/inet6_opt_init.3 @@ -0,0 +1,291 @@ +.\" $KAME: inet6_opt_init.3,v 1.5 2002/10/17 14:13:47 jinmei Exp $ +.\" +.\" Copyright (C) 2000 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 5, 2000 +.Dt INET6_OPT_INIT 3 +.Os +.\" +.Sh NAME +.Nm inet6_opt_init , +.Nm inet6_opt_append , +.Nm inet6_opt_finish , +.Nm inet6_opt_set_val , +.Nm inet6_opt_next , +.Nm inet6_opt_find , +.Nm inet6_opt_get_val +.Nd IPv6 Hop-by-Hop and Destination Options manipulation +.\" +.Sh SYNOPSIS +.In netinet/in.h +.Ft "int" +.Fn inet6_opt_init "void *extbuf" "socklen_t extlen" +.Ft "int" +.Fn inet6_opt_append "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t len" "u_int8_t align" "void **databufp" +.Ft "int" +.Fn inet6_opt_finish "void *extbuf" "socklen_t extlen" "int offset" +.Ft "int" +.Fn inet6_opt_set_val "void *databuf" "int offset" "void *val" "socklen_t vallen" +.Ft "int" +.Fn inet6_opt_next "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t *typep" "socklen_t *lenp" "void **databufp" +.Ft "int" +.Fn inet6_opt_find "void *extbuf" "socklen_t extlen" "int offset" "u_int8_t type" "socklen_t *lenp" "void **databufp" +.Ft "int" +.Fn inet6_opt_get_val "void *databuf" "socklen_t offset" "void *val" "socklen_t vallen" +.\" +.Sh DESCRIPTION +Building and parsing the Hop-by-Hop and Destination options is +complicated. +The advanced API therefore defines a set +of functions to help applications. +These functions assume the +formatting rules specified in Appendix B in RFC2460 i.e. that the +largest field is placed last in the option. +The function prototypes for +these functions are all in the +.Aq Li netinet/in.h +header. +.\" +.Ss inet6_opt_init +.Fn inet6_opt_init +returns the number of bytes needed for the empty +extension header i.e. without any options. +If +.Li extbuf +is not NULL it also initializes the extension header to have the correct length +field. +In that case if the +.Li extlen value is not a positive +.Po +i.e., non-zero +.Pc +multiple of 8 the function fails and returns -1. +.\" +.Ss inet6_opt_append +.Fn inet6_opt_append +returns the updated total length taking into account +adding an option with length +.Li len +and alignment +.Li align . +.Li Offset +should be the length returned by +.Fn inet6_opt_init +or a previous +.Fn inet6_opt_append . +If +.Li extbuf +is not NULL then, in addition to returning the length, +the function inserts any needed pad option, initializes the option +.Po +setting the type and length fields +.Pc +and returns a pointer to the location for the option content in +.Li databufp . +.Pp +.Li type +is the 8-bit option type. +.Li len +is the length of the option data +.Po +i.e. excluding the option type and option length fields. +.Pc +.Pp +Once +.Fn inet6_opt_append +has been called the application can use the +databuf directly, or use +.Fn inet6_opt_set_val +to specify the content of the option. +.Pp +The option type must have a value from 2 to 255, inclusive. +.Po +0 and 1 are reserved for the Pad1 and PadN options, respectively. +.Pc +.Pp +The option data length must have a value between 0 and 255, +inclusive, and is the length of the option data that follows. +.Pp +The +.Li align +parameter must have a value of 1, 2, 4, or 8. +The align value can not exceed the value of +.Li len . +.\" +.Ss inet6_opt_finish +.Fn inet6_opt_finish +returns the updated total length +taking into account the final padding of the extension header to make +it a multiple of 8 bytes. +.Li Offset +should be the length returned by +.Fn inet6_opt_init +or +.Fn inet6_opt_append . +If +.Li extbuf +is not NULL the function also +initializes the option by inserting a Pad1 or PadN option of the +proper length. +.Pp +If the necessary pad does not fit in the extension header buffer the +function returns -1. +.\" +.Ss inet6_opt_set_val +.Fn inet6_opt_set_val +inserts data items of various sizes in the data portion of the option. +.Li Databuf +should be a pointer returned by +.Fn inet6_opt_append . +.Li val +should point to the data to be +inserted. +.Li Offset +specifies where in the data portion of the option +the value should be inserted; the first byte after the option type +and length is accessed by specifying an offset of zero. +.Pp +The caller should ensure that each field is aligned on its natural +boundaries as described in Appendix B of RFC2460, but the function +must not rely on the caller's behavior. +Even when the alignment requirement is not satisfied, +the function should just copy the data as required. +.Pp +The function returns the offset for the next field +.Po +i.e., +.Li offset ++ +.Li vallen +.Pc +which can be used when composing option content with multiple fields. +.\" +.Ss inet6_opt_next +.Fn inet6_opt_next +parses received extension headers returning the next +option. +.Li Extbuf +and +.Li extlen +specifies the extension header. +.Li Offset +should either be zero (for the first option) or the length returned +by a previous call to +.Fn inet6_opt_next +or +.Fn inet6_opt_find . +It specifies the position where to continue scanning the extension +buffer. +The next option is returned by updating +.Li typep , +.Li lenp , +and +.Li databufp . +This function returns the updated +.Dq previous +length +computed by advancing past the option that was returned. +This returned +.Dq previous +length can then be passed to subsequent calls to +.Fn inet6_opt_next . +This function does not return any PAD1 or PADN options. +When there are no more options the return value is -1. +.\" +.Ss inet6_opt_get_val +.Fn inet6_opt_get_val +This function extracts data items of various sizes +in the data portion of the option. +.Li Databuf +should be a pointer returned by +.Fn inet6_opt_next +or +.Fn inet6_opt_find . +.Li Val +should point to the destination for the extracted data. +.Li Offset +specifies from where in the data portion of the option the value should be +extracted; the first byte after the option type and length is +accessed by specifying an offset of zero. +.Pp +It is expected that each field is aligned on its natural boundaries +as described in Appendix B of RFC2460, but the function must not +rely on the alignment. +.Pp +The function returns the offset for the next field +.Po +i.e., +.Li offset ++ +.Li vallen +.Pc +which can be used when extracting option content with +multiple fields. +Robust receivers might want to verify alignment before calling +this function. +.\" +.Sh DIAGNOSTICS +All the functions ruturn +.Li -1 +on an error. +.\" +.Sh EXAMPLES +draft-ietf-ipngwg-rfc2292bis-08.txt +gives comprehensive examples in Section 23. +.Pp +KAME also provides examples in the advapitest directry of its kit. +.\" +.Sh SEE ALSO +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T "Advanced Sockets API for IPv6" +.%N draft-ietf-ipngwg-rfc2292bis-08 +.%D October 2002 +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%T "Internet Protocol, Version 6 (IPv6) Specification" +.%N RFC2460 +.%D December 1998 +.Re +.Sh HISTORY +The implementation first appeared in KAME advanced networking kit. +.Sh STANDARDS +The functions +are documented in +.Dq Advanced Sockets API for IPv6 +.Pq draft-ietf-ipngwg-rfc2292bis-08.txt . +.\" +.Sh BUGS +The text was shamelessly copied from internet-drafts for RFC2292bis. |
