'\" te
.\"  Copyright 2003 AT&T
.\" Copyright (C) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH INET6_OPT 3SOCKET "Feb 15, 2007"
.SH NAME
inet6_opt, inet6_opt_init, inet6_opt_append, inet6_opt_finish,
inet6_opt_set_val, inet6_opt_next, inet6_opt_find, inet6_opt_get_val \- Option
manipulation mechanism
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR [\fIlibrary...\fR]
#include <netinet/in.h>

\fBint\fR \fBinet6_opt_init\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR);
.fi

.LP
.nf
\fBint\fR \fBinet6_opt_append\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR,
     \fBint\fR \fIoffset\fR, \fBuint8_t\fR \fItype\fR, \fBsocklen_t\fR \fIlen\fR, \fBuint_t\fR \fIalign\fR,
     \fBvoid **\fR\fIdatabufp\fR);
.fi

.LP
.nf
\fBint\fR \fBinet6_opt_finish\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR,
     \fBint\fR \fIoffset\fR);
.fi

.LP
.nf
\fBint\fR \fBinet6_opt_set_val\fR(\fBvoid *\fR\fIdatabuf\fR, \fBint\fR \fIoffset\fR,
     \fBvoid *\fR\fIval\fR, \fBsocklen_t\fR \fIvallen\fR);
.fi

.LP
.nf
\fBint\fR \fBinet6_opt_next\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR,
     \fBint\fR \fIoffset\fR, \fBuint8_t *\fR\fItypep\fR, \fBsocklen_t *\fR\fIlenp\fR,
     \fBvoid **\fR\fIdatabufp\fR);
.fi

.LP
.nf
\fBint\fR \fBinet6_opt_find\fR(\fBvoid *\fR\fIextbuf\fR, \fBsocklen_t\fR \fIextlen\fR, \fBint\fR \fIoffset\fR,
     \fBuint8_t\fR \fItype\fR, \fBsocklen_t *\fR\fIlenp\fR, \fBvoid **\fR\fIdatabufp\fR);
.fi

.LP
.nf
\fBint\fR\fBinet6_opt_get_val\fR(\fBvoid *\fR\fIdatabuf\fR, \fBint\fR \fIoffset\fR,
     \fBvoid *\fR\fIval\fR, \fBsocklen_t *\fR\fIvallen\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBinet6_opt\fR functions enable users to manipulate options without having
to know the structure of the option header.
.sp
.LP
The \fBinet6_opt_init()\fR function returns the number of bytes needed for the
empty extension header, that is, without any options. If \fIextbuf\fR is not
\fBNULL\fR, it also initializes the extension header to the correct length
field. If the \fIextlen\fR value is not a positive non-zero multiple of 8, the
function fails and returns \fB-1\fR\&.
.sp
.LP
The \fBinet6_opt_append()\fR function returns the updated total length while
adding an option with length \fBlen\fR and alignment \fBalign\fR. If
\fIextbuf\fR is not \fBNULL\fR, then, in addition to returning the length, the
function inserts any needed Pad option, initializes the option setting the type
and length fields, and returns a pointer to the location for the option content
in \fIdatabufp\fR. If the option does not fit in the extension header buffer,
the function returns \fB-1\fR\&. The \fItype\fR is the 8-bit option type. The
\fIlen\fR is the length of the option data, excluding the option type and
option length fields. Once \fBinet6_opt_append()\fR is called, the application
can use the \fIdatabuf\fR directly, or \fBinet6_opt_set_val()\fR can be used to
specify the content of the option. The option type must have a value from 2 to
255, inclusive. The values 0 and 1 are reserved for the Pad1 and PadN options,
respectively. The option data length must have a value between 0 and 255,
inclusive, and it is the length of the option data that follows. The align
parameter must have a value of 1, 2, 4, or 8. The align value cannot exceed the
value of \fBlen\fR.
.sp
.LP
The \fBinet6_opt_finish()\fR function returns the updated total length the
takes into account the final padding of the extension header to make it a
multiple of 8 bytes. If \fIextbuf\fR is not \fBNULL\fR, the function also
initializes the option by inserting a Pad1 or PadN option of the proper length.
If the necessary pad does not fit in the extension header buffer, the function
returns \fB-1\fR\&.
.sp
.LP
The \fBinet6_opt_set_val()\fR function inserts data items of various sizes in
the data portion of the option. The \fIval\fR parameter should point to the
data to be inserted. The \fIoffset\fR specifies the data portion of the option
in which the value should be inserted. The first byte after the option type and
length is accessed by specifying an \fIoffset\fR of zero.
.sp
.LP
The \fBinet6_opt_next()\fR function parses the received option extension
headers which return the next option. The \fIextbuf\fR and \fIextlen\fR
parameters specify the extension header. The \fIoffset\fR should be zero for
the first option or the length returned by a previous call to either
\fBinet6_opt_next()\fR or \fBinet6_opt_find()\fR. The \fIoffset\fR specifies
where to continue scanning the extension buffer. The subsequent option is
returned by updating \fItypep\fR, \fIlenp\fR, and \fIdatabufp\fR. The
\fItypep\fR argument stores the option type. The \fIlenp\fR argument stores the
length of the option data, excluding the option type and option length fields.
The \fIdatabufp\fR argument points to the data field of the option.
.sp
.LP
The \fBinet6_opt_find()\fR function is similar to the \fBinet6_opt_next()\fR
function. Unlike \fBinet6_opt_next()\fR, the \fBinet6_opt_find()\fR function
enables the caller to specify the option type to be searched for, rather than
returning the next option in the extension header.
.sp
.LP
The \fBinet6_opt_get_val()\fR function extracts data items of various sizes in
the portion of the option. The \fIval\fR argument should point to the
destination for the extracted data. The \fIoffset\fR specifies at which point
in the option's data portion the value should be extracted. The first byte
following the option type and length is accessed by specifying an \fIoffset\fR
of zero.
.SH RETURN VALUES
.sp
.LP
The \fBinet6_opt_init()\fR function returns the number of bytes needed for the
empty extension header. If the \fIextlen\fR value is not a positive non-zero
multiple of 8, the function fails and returns \fB-1\fR\&.
.sp
.LP
The \fBinet6_opt_append()\fR function returns the updated total length.
.sp
.LP
The \fBinet6_opt_finish()\fR function returns the updated total length.
.sp
.LP
The \fBinet6_opt_set_val()\fR function returns the \fIoffset\fR for the
subsequent field.
.sp
.LP
The \fBinet6_opt_next()\fR function returns the updated "previous" length
computed by advancing past the option that was returned. When there are no
additional options or if the option extension header is malformed, the return
value is \fB-1\fR\&.
.sp
.LP
The \fBinet6_opt_find()\fR function returns the updated "previous" total
length. If an option of the specified type is not located, the return value is
\fB-1\fR\&. If the option extension header is malformed, the return value is
\fB-1\fR\&.
.sp
.LP
The \fBinet6_opt_get_val()\fR function returns the \fIoffset\fR for the next
field (that is, \fIoffset\fR + \fIvallen\fR) which can be used when extracting
option content with multiple fields.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
RFC 3542 - \fIAdvanced Sockets Application Programming Interface (API) for
IPv6\fR, The Internet Society. May 2003