'\" te
.\" Copyright (c) 2006, 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 NVLIST_NEXT_NVPAIR 9F "Jan 16, 2006"
.SH NAME
nvlist_next_nvpair, nvpair_name, nvpair_type \- return data regarding
name-value pairs
.SH SYNOPSIS
.nf
#include <sys/nvpair.h>

\fBnvpair_t *\fR\fBnvlist_next_nvpair\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvpair_t *\fR\fInvpair\fR);
.fi

.LP
.nf
\fBchar *\fR\fBnvpair_name\fR(\fBnvpair_t *\fR\fInvpair\fR);
.fi

.LP
.nf
\fBdata_type_t\fR \fBnvpair_type\fR(\fBnvpair_t *\fR\fInvpair\fR);
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI)
.SH PARAMETERS
.ne 2
.na
\fB\fInvl\fR\fR
.ad
.RS 10n
The list of name-value pairs (\fBnvlist_t\fR) to be processed.
.RE

.sp
.ne 2
.na
\fB\fInvpair\fR\fR
.ad
.RS 10n
Handle to a name-value pair.
.RE

.SH DESCRIPTION
The \fBnvlist_next_nvpair()\fR function returns a handle to the next name-value
pair (\fBnvpair\fR) in the list following \fInvpair\fR. If \fInvpair\fR is
NULL, the first pair is returned. If \fInvpair\fR is the last pair in the
\fBnvlist_t\fR, NULL is returned.
.sp
.LP
The \fBnvpair_name()\fR function returns a string containing the name of
\fInvpair\fR.
.sp
.LP
The \fBnvpair_type()\fR function retrieves the value of the \fInvpair\fR in the
form of enumerated type \fBdata_type_t\fR. This is used to determine the
appropriate \fBnvpair_*()\fR function to call for retrieving the value.
.SH RETURN VALUES
For \fBnvpair_name()\fR: a string containing the name.
.sp
.LP
For \fBnvpair_type()\fR: an enumerated data type \fBdata_type_t\fR. Possible
values for \fBdata_type_t\fR are:
.sp
.in +2
.nf
DATA_TYPE_BOOLEAN
DATA_TYPE_BOOLEAN_VALUE
DATA_TYPE_BYTE
DATA_TYPE_INT8
DATA_TYPE_UINT8
DATA_TYPE_INT16
DATA_TYPE_UINT16
DATA_TYPE_INT32
DATA_TYPE_UINT32
DATA_TYPE_INT64
DATA_TYPE_UINT64
DATA_TYPE_STRING
DATA_TYPE_NVLIST
DATA_TYPE_BOOLEAN_ARRAY
DATA_TYPE_BYTE_ARRAY
DATA_TYPE_INT8_ARRAY
DATA_TYPE_UINT8_ARRAY
DATA_TYPE_INT16_ARRAY
DATA_TYPE_UINT16_ARRAY
DATA_TYPE_INT32_ARRAY
DATA_TYPE_UINT32_ARRAY
DATA_TYPE_INT64_ARRAY
DATA_TYPE_UINT64_ARRAY
DATA_TYPE_STRING_ARRAY
DATA_TYPE_NVLIST_ARRAY
.fi
.in -2
.sp

.sp
.LP
After nvpairs is removed from or replaced in an nvlist, it cannot be
manipulated. This includes \fBnvlist_next_nvpair()\fR, \fBnvpair_name()\fR and
\fBnvpair_type()\fR. Replacement can happen during pair addition on nvlists
created with NV_UNIQUE_NAME_TYPE and NV_UNIQUE_NAME. See \fBnvlist_alloc\fR(9F)
for more details.
.SH CONTEXT
These functions can be called from user, interrupt, or kernel context.