share/man/man3nvpair/nvlist_next_nvpair.3nvpair

   1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH NVLIST_NEXT_NVPAIR 3NVPAIR "Feb 2, 2004"
   7 .SH NAME
   8 nvlist_next_nvpair, nvpair_name, nvpair_type \- return data regarding
   9 name-value pairs
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnvpair\fR [ \fIlibrary\fR... ]
  14 #include <libnvpair.h>
  15
  16 \fBnvpair_t *\fR\fBnvlist_next_nvpair\fR(\fBnvlist_t *\fR\fInvl\fR, \fBnvpair_t *\fR\fInvpair\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBchar *\fR\fBnvpair_name\fR(\fBnvpair_t *\fR\fInvpair\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBdata_type_t\fR \fBnvpair_type\fR(\fBnvpair_t *\fR\fInvpair\fR);
  27 .fi
  28
  29 .SH PARAMETERS
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fInvl\fR\fR
  34 .ad
  35 .RS 10n
  36 The \fBnvlist_t\fR to be processed.
  37 .RE
  38
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fInvpair\fR\fR
  43 .ad
  44 .RS 10n
  45 Handle to a name-value pair.
  46 .RE
  47
  48 .SH DESCRIPTION
  49 .sp
  50 .LP
  51 The \fBnvlist_next_nvpair()\fR function returns a handle to the next
  52 \fBnvpair\fR in the list following \fBnvpair\fR. If \fBnvpair\fR is \fINULL\fR,
  53 the first pair is returned. If \fBnvpair\fR is the last pair in the
  54 \fBnvlist\fR, \fINULL\fR is returned.
  55 .sp
  56 .LP
  57 The \fBnvpair_name()\fR function returns a string containing the name of
  58 \fBnvpair\fR.
  59 .sp
  60 .LP
  61 The \fBnvpair_type()\fR function retrieves the value of the \fBnvpair\fR in the
  62 form of enumerated type \fBdata_type_t\fR. This is used to determine the
  63 appropriate \fBnvpair_*()\fR function to call for retrieving the value.
  64 .SH RETURN VALUES
  65 .sp
  66 .LP
  67 Upon successful completion, \fBnvpair_name()\fR returns a string containing the
  68 name of the name-value pair.
  69 .sp
  70 .LP
  71 Upon successful completion, \fBnvpair_type()\fR returns an enumerated data type
  72 \fBdata_type_t\fR. Possible values for \fBdata_type_t\fR are as follows:
  73 .RS +4
  74 .TP
  75 .ie t \(bu
  76 .el o
  77 \fBDATA_TYPE_BOOLEAN\fR
  78 .RE
  79 .RS +4
  80 .TP
  81 .ie t \(bu
  82 .el o
  83 \fBDATA_TYPE_BOOLEAN_VALUE\fR
  84 .RE
  85 .RS +4
  86 .TP
  87 .ie t \(bu
  88 .el o
  89 \fBDATA_TYPE_BYTE\fR
  90 .RE
  91 .RS +4
  92 .TP
  93 .ie t \(bu
  94 .el o
  95 \fBDATA_TYPE_INT8\fR
  96 .RE
  97 .RS +4
  98 .TP
  99 .ie t \(bu
 100 .el o
 101 \fBDATA_TYPE_UINT8\fR
 102 .RE
 103 .RS +4
 104 .TP
 105 .ie t \(bu
 106 .el o
 107 \fBDATA_TYPE_INT16\fR
 108 .RE
 109 .RS +4
 110 .TP
 111 .ie t \(bu
 112 .el o
 113 \fBDATA_TYPE_UINT16\fR
 114 .RE
 115 .RS +4
 116 .TP
 117 .ie t \(bu
 118 .el o
 119 \fBDATA_TYPE_INT32\fR
 120 .RE
 121 .RS +4
 122 .TP
 123 .ie t \(bu
 124 .el o
 125 \fBDATA_TYPE_UINT32\fR
 126 .RE
 127 .RS +4
 128 .TP
 129 .ie t \(bu
 130 .el o
 131 \fBDATA_TYPE_INT64\fR
 132 .RE
 133 .RS +4
 134 .TP
 135 .ie t \(bu
 136 .el o
 137 \fBDATA_TYPE_UINT64\fR
 138 .RE
 139 .RS +4
 140 .TP
 141 .ie t \(bu
 142 .el o
 143 \fBDATA_TYPE_STRING\fR
 144 .RE
 145 .RS +4
 146 .TP
 147 .ie t \(bu
 148 .el o
 149 \fBDATA_TYPE_NVLIST\fR
 150 .RE
 151 .RS +4
 152 .TP
 153 .ie t \(bu
 154 .el o
 155 \fBDATA_TYPE_BOOLEAN_ARRAY\fR
 156 .RE
 157 .RS +4
 158 .TP
 159 .ie t \(bu
 160 .el o
 161 \fBDATA_TYPE_BYTE_ARRAY\fR
 162 .RE
 163 .RS +4
 164 .TP
 165 .ie t \(bu
 166 .el o
 167 \fBDATA_TYPE_INT8_ARRAY\fR
 168 .RE
 169 .RS +4
 170 .TP
 171 .ie t \(bu
 172 .el o
 173 \fBDATA_TYPE_UINT8_ARRAY\fR
 174 .RE
 175 .RS +4
 176 .TP
 177 .ie t \(bu
 178 .el o
 179 \fBDATA_TYPE_INT16_ARRAY\fR
 180 .RE
 181 .RS +4
 182 .TP
 183 .ie t \(bu
 184 .el o
 185 \fBDATA_TYPE_UINT16_ARRAY\fR
 186 .RE
 187 .RS +4
 188 .TP
 189 .ie t \(bu
 190 .el o
 191 \fBDATA_TYPE_INT32_ARRAY\fR
 192 .RE
 193 .RS +4
 194 .TP
 195 .ie t \(bu
 196 .el o
 197 \fBDATA_TYPE_UINT32_ARRAY\fR
 198 .RE
 199 .RS +4
 200 .TP
 201 .ie t \(bu
 202 .el o
 203 \fBDATA_TYPE_INT64_ARRAY\fR
 204 .RE
 205 .RS +4
 206 .TP
 207 .ie t \(bu
 208 .el o
 209 \fBDATA_TYPE_UINT64_ARRAY\fR
 210 .RE
 211 .RS +4
 212 .TP
 213 .ie t \(bu
 214 .el o
 215 \fBDATA_TYPE_STRING_ARRAY\fR
 216 .RE
 217 .RS +4
 218 .TP
 219 .ie t \(bu
 220 .el o
 221 \fBDATA_TYPE_NVLIST_ARRAY\fR
 222 .RE
 223 .sp
 224 .LP
 225 Upon reaching the end of a list, \fBnvlist_next_pair()\fR returns \fINULL\fR.
 226 Otherwise, the function returns a handle to next \fBnvpair\fR in the list.
 227 .sp
 228 .LP
 229 These and other \fBlibnvpair\fR(3LIB) functions cannot manipulate nvpairs after
 230 they have been removed from or replaced in an nvlist. Replacement can occur
 231 during pair additions to nvlists created with \fBNV_UNIQUE_NAME_TYPE\fR and
 232 \fBNV_UNIQUE_NAME\fR. See \fBnvlist_alloc\fR(3NVPAIR).
 233 .SH ERRORS
 234 .sp
 235 .LP
 236 No errors are defined.
 237 .SH EXAMPLES
 238 .LP
 239 \fBExample 1 \fRExample of usage of \fBnvlist_next_nvpair()\fR.
 240 .sp
 241 .in +2
 242 .nf
 243 /*
 244  * usage of nvlist_next_nvpair()
 245  */
 246  static int
 247  edit_nvl(nvlist_t *nvl)
 248  {
 249      nvpair_t *curr = nvlist_next_nvpair(nvl, NULL);
 250
 251      while (curr != NULL) {
 252          int err;
 253         nvpair_t *next = nvlist_next_nvpair(nvl, curr);
 254
 255         if (!nvl_check(curr))
 256             if ((err = nvlist_remove(nvl, nvpair_name(curr),
 257                 nvpair_type(curr))) != 0)
 258                     return (err);
 259
 260          curr = next;
 261      }
 262     return (0);
 263  }
 264 .fi
 265 .in -2
 266
 267 .SH ATTRIBUTES
 268 .sp
 269 .LP
 270 See \fBattributes\fR(5) for descriptions of the following attributes:
 271 .sp
 272
 273 .sp
 274 .TS
 275 box;
 276 c | c
 277 l | l .
 278 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 279 _
 280 Interface Stability     Evolving
 281 _
 282 MT-Level        MT-Safe
 283 .TE
 284
 285 .SH SEE ALSO
 286 .sp
 287 .LP
 288 \fBlibnvpair\fR(3LIB), \fBnvlist_alloc\fR(3NVPAIR), \fBattributes\fR(5)
 289 .SH NOTES
 290 .sp
 291 .LP
 292 The enumerated nvpair data types might not be an exhaustive list and new data
 293 types can be added.  An application using the data type enumeration,
 294 \fBdata_type_t\fR, should be written to expect or ignore new data types.