diff options
Diffstat (limited to 'lib/libc/net/inet6_opt_init.3')
| -rw-r--r-- | lib/libc/net/inet6_opt_init.3 | 150 |
1 files changed, 89 insertions, 61 deletions
diff --git a/lib/libc/net/inet6_opt_init.3 b/lib/libc/net/inet6_opt_init.3 index 410241406b82b..88dd4837c7042 100644 --- a/lib/libc/net/inet6_opt_init.3 +++ b/lib/libc/net/inet6_opt_init.3 @@ -66,108 +66,129 @@ 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 +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 +.In netinet/in.h header. .\" .Ss inet6_opt_init +The .Fn inet6_opt_init +function returns the number of bytes needed for the empty -extension header i.e., without any options. +extension header, i.e., without any options. If -.Li extbuf -is not NULL it also initializes the extension header to have the correct length +.Va extbuf +is not +.Dv 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. +.Fa extlen +value is not a positive +(i.e., non-zero) +multiple of 8 the function fails and returns \-1. .\" .Ss inet6_opt_append +The .Fn inet6_opt_append +function returns the updated total length taking into account adding an option with length -.Li len +.Fa len and alignment -.Li align . -.Li Offset +.Fa align . +The +.Fa offset +argument 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, +.Fa extbuf +is not +.Dv 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 +(setting the type and length fields) and returns a pointer to the location for the option content in -.Li databufp . +.Fa databufp . .Pp -.Li type +The +.Fa type +argument is the 8-bit option type. -.Li len +The +.Fa len +argument is the length of the option data -.Po -i.e., excluding the option type and option length fields. -.Pc +(i.e., excluding the option type and option length fields). .Pp Once .Fn inet6_opt_append -has been called the application can use the +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 +(0 and 1 are reserved for the Pad1 and PadN options, respectively.) .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 +.Fa align parameter must have a value of 1, 2, 4, or 8. The align value can not exceed the value of -.Li len . +.Fa len . .\" .Ss inet6_opt_finish +The .Fn inet6_opt_finish +function 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 +The +.Fa offset +argument should be the length returned by .Fn inet6_opt_init or .Fn inet6_opt_append . If -.Li extbuf -is not NULL the function also +.Fa extbuf +is not +.Dv 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. +function returns \-1. .\" .Ss inet6_opt_set_val +The .Fn inet6_opt_set_val +function inserts data items of various sizes in the data portion of the option. -.Li Databuf +The +.Fa databuf +argument should be a pointer returned by .Fn inet6_opt_append . -.Li val +The +.Fa val +argument should point to the data to be inserted. -.Li Offset +The +.Fa offset +argument 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. @@ -179,24 +200,27 @@ 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 +(i.e., +.Fa offset + -.Li vallen -.Pc +.Fa vallen ) which can be used when composing option content with multiple fields. .\" .Ss inet6_opt_next +The .Fn inet6_opt_next +function parses received extension headers returning the next option. -.Li Extbuf +The +.Fa extbuf and -.Li extlen -specifies the extension header. -.Li Offset -should either be zero (for the first option) or the length returned +.Fa extlen +arguments specify the extension header. +The +.Fa offset +argument +should either be zero (for the first option), or the length returned by a previous call to .Fn inet6_opt_next or @@ -204,10 +228,9 @@ or It specifies the position where to continue scanning the extension buffer. The next option is returned by updating -.Li typep , -.Li lenp , +.Fa typep , lenp , and -.Li databufp . +.Fa databufp . This function returns the updated .Dq previous length @@ -217,20 +240,27 @@ This returned 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. +When there are no more options the return value is \-1. .\" .Ss inet6_opt_get_val +The .Fn inet6_opt_get_val -This function extracts data items of various sizes +function extracts data items of various sizes in the data portion of the option. -.Li Databuf +The +.Fa databuf +argument should be a pointer returned by .Fn inet6_opt_next or .Fn inet6_opt_find . -.Li Val +The +.Fa val +argument should point to the destination for the extracted data. -.Li Offset +The +.Fa offset +argument 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. @@ -240,12 +270,10 @@ 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 +(i.e., +.Fa offset + -.Li vallen -.Pc +.Fa vallen ) which can be used when extracting option content with multiple fields. Robust receivers might want to verify alignment before calling @@ -253,7 +281,7 @@ this function. .\" .Sh DIAGNOSTICS All the functions return -.Li -1 +\-1 on an error. .\" .Sh EXAMPLES |