usr/src/man/man9f/nvlist_lookup_boolean.9f

   1 '\" te
   2 .\" Copyright (c) 2006, 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_LOOKUP_BOOLEAN 9F "May 20, 2006"
   7 .SH NAME
   8 nvlist_lookup_boolean, nvlist_lookup_boolean_value, nvlist_lookup_byte,
   9 nvlist_lookup_int8, nvlist_lookup_int16, nvlist_lookup_int32,
  10 nvlist_lookup_int64, nvlist_lookup_uint8, nvlist_lookup_uint16,
  11 nvlist_lookup_uint32, nvlist_lookup_uint64, nvlist_lookup_string,
  12 nvlist_lookup_nvlist, nvlist_lookup_boolean_array, nvlist_lookup_byte_array,
  13 nvlist_lookup_int8_array, nvlist_lookup_int16_array, nvlist_lookup_int32_array,
  14 nvlist_lookup_int64_array, nvlist_lookup_uint8_array,
  15 nvlist_lookup_uint16_array, nvlist_lookup_uint32_array,
  16 nvlist_lookup_uint64_array, nvlist_lookup_string_array,
  17 nvlist_lookup_nvlist_array, nvlist_lookup_pairs \- match name and type
  18 indicated by the interface name and retrieve data value
  19 .SH SYNOPSIS
  20 .LP
  21 .nf
  22 #include <sys/nvpair.h>
  23
  24 \fBint\fR \fBnvlist_lookup_boolean\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBnvlist_lookup_boolean_value\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  30      \fBboolean_t *\fR\fIval\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBint\fR \fBnvlist_lookup_byte\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  36      \fBuchar_t *\fR\fIval\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBnvlist_lookup_int8\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  42      \fBint8_t *\fR\fIval\fR);
  43 .fi
  44
  45 .LP
  46 .nf
  47 \fBint\fR \fBnvlist_lookup_uint8\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  48      \fBuint8_t *\fR\fIval\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBint\fR \fBnvlist_lookup_int16\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  54      \fBint16_t *\fR\fIval\fR);
  55 .fi
  56
  57 .LP
  58 .nf
  59 \fBint\fR \fBnvlist_lookup_uint16\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  60      \fBuint16_t *\fR\fIval\fR);
  61 .fi
  62
  63 .LP
  64 .nf
  65 \fBint\fR \fBnvlist_lookup_int32\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  66      \fBint32_t *\fR\fIval\fR);
  67 .fi
  68
  69 .LP
  70 .nf
  71 \fBint\fR \fBnvlist_lookup_uint32\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  72      \fBuint32_t *\fR\fIval\fR);
  73 .fi
  74
  75 .LP
  76 .nf
  77 \fBint\fR \fBnvlist_lookup_int64\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  78      \fBint64_t *\fR\fIval\fR);
  79 .fi
  80
  81 .LP
  82 .nf
  83 \fBint\fR \fBnvlist_lookup_uint64\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  84      \fBuint64_t *\fR\fIval\fR);
  85 .fi
  86
  87 .LP
  88 .nf
  89 \fBint\fR \fBnvlist_lookup_string\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  90      \fBchar **\fR\fIval\fR);
  91 .fi
  92
  93 .LP
  94 .nf
  95 \fBint\fR \fBnvlist_lookup_nvlist\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
  96      \fBnvlist_t **\fR\fIval\fR);
  97 .fi
  98
  99 .LP
 100 .nf
 101 \fBint\fR \fBnvlist_lookup_boolean_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 102      \fBboolean_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 103 .fi
 104
 105 .LP
 106 .nf
 107 \fBint\fR \fBnvlist_lookup_byte_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 108      \fBuchar_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 109 .fi
 110
 111 .LP
 112 .nf
 113 \fBint\fR \fBnvlist_lookup_int8_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 114      \fBint8_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 115 .fi
 116
 117 .LP
 118 .nf
 119 \fBint\fR \fBnvlist_lookup_uint8_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 120      \fBuint8_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 121 .fi
 122
 123 .LP
 124 .nf
 125 \fBint\fR \fBnvlist_lookup_int16_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 126      \fBint16_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 127 .fi
 128
 129 .LP
 130 .nf
 131 \fBint\fR \fBnvlist_lookup_uint16_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 132      \fBuint16_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 133 .fi
 134
 135 .LP
 136 .nf
 137 \fBint\fR \fBnvlist_lookup_int32_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 138      \fBint32_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 139 .fi
 140
 141 .LP
 142 .nf
 143 \fBint\fR \fBnvlist_lookup_uint32_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 144      \fBuint32_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 145 .fi
 146
 147 .LP
 148 .nf
 149 \fBint\fR \fBnvlist_lookup_int64_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 150      \fBint64_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 151 .fi
 152
 153 .LP
 154 .nf
 155 \fBint\fR \fBnvlist_lookup_uint64_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 156      \fBuint64_t **\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 157 .fi
 158
 159 .LP
 160 .nf
 161 \fBint\fR \fBnvlist_lookup_string_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 162      \fBchar  ***\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 163 .fi
 164
 165 .LP
 166 .nf
 167 \fBint\fR \fBnvlist_lookup_nvlist_array\fR(\fBnvlist_t *\fR\fInvl\fR, \fBconst char *\fR\fIname\fR,
 168      \fBnvlist_t ***\fR\fIval\fR, \fBuint_t *\fR\fInelem\fR);
 169 .fi
 170
 171 .LP
 172 .nf
 173 \fBint\fR \fBnvlist_lookup_pairs\fR(\fBnvlist_t *\fR\fInvl\fR, \fBint\fR \fIflag, ...\fR);
 174 .fi
 175
 176 .SH INTERFACE LEVEL
 177 .sp
 178 .LP
 179 Solaris DDI specific (Solaris DDI)
 180 .SH PARAMETERS
 181 .sp
 182 .ne 2
 183 .na
 184 \fB\fInvl\fR\fR
 185 .ad
 186 .RS 9n
 187 The list of name-value pairs (\fBnvlist_t\fR) to be processed.
 188 .RE
 189
 190 .sp
 191 .ne 2
 192 .na
 193 \fB\fIname\fR\fR
 194 .ad
 195 .RS 9n
 196 Name of the name-value pair (\fBnvpair\fR) to search.
 197 .RE
 198
 199 .sp
 200 .ne 2
 201 .na
 202 \fB\fInelem\fR\fR
 203 .ad
 204 .RS 9n
 205 Address to store the number of elements in value.
 206 .RE
 207
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fIval\fR\fR
 212 .ad
 213 .RS 9n
 214 Address to store the value or starting address of the array value.
 215 .RE
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fIflag\fR\fR
 221 .ad
 222 .RS 9n
 223 Specify bit fields defining lookup behavior:
 224 .sp
 225 .ne 2
 226 .na
 227 \fBNV_FLAG_NOENTOK\fR
 228 .ad
 229 .RS 19n
 230 The retrival function will not fail if no matching name-value pair is found.
 231 .RE
 232
 233 .RE
 234
 235 .SH DESCRIPTION
 236 .sp
 237 .LP
 238 These functions find the \fBnvpair\fR that matches the name and type as
 239 indicated by the interface name. If one is found, \fInelem\fR and \fIval\fR are
 240 modified to contain the number of elements in value and the starting address of
 241 data, respectively.
 242 .sp
 243 .LP
 244 These interfaces work for \fBnvlist_t\fR allocated with \fBNV_UNIQUE_NAME\fR or
 245 \fBNV_UNIQUE_NAME_TYPE\fR specified in \fBnvlist_alloc()\fR. See
 246 \fBnvlist_alloc\fR(9F). If this is not the case, the interface will return
 247 \fBENOTSUP\fR because the list potentially contains multiple \fBnvpair\fRs with
 248 the same name and type.
 249 .sp
 250 .LP
 251 Multiple threads can simultaneously read the same \fBnvlist_t\fR but only one
 252 thread should actively change a given \fBnvlist_t\fR at a time. The caller is
 253 responsible for the synchronization.
 254 .sp
 255 .LP
 256 All memory required for storing the array elements, including string values,
 257 are managed by the library. References to such data remain valid until
 258 \fBnvlist_free()\fR is called on \fInvl\fR.
 259 .sp
 260 .LP
 261 The \fBnvlist_lookup_pairs()\fR function retrieves a set of \fBnvpair\fRs. The
 262 arguments are a null-terminated list of pairs (data type
 263 \fBDATA_TYPE_BOOLEAN\fR), triples (non-array data types) or quads (array data
 264 types). As shown below, the interpretation of the arguments depends on the
 265 value of \fItype\fR. See \fBnvpair_type\fR(9F).
 266 .sp
 267 .ne 2
 268 .na
 269 \fB\fIname\fR\fR
 270 .ad
 271 .RS 9n
 272 Name of the name-value pair to search.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fItype\fR\fR
 279 .ad
 280 .RS 9n
 281 Data type.
 282 .RE
 283
 284 .sp
 285 .ne 2
 286 .na
 287 \fB\fIval\fR\fR
 288 .ad
 289 .RS 9n
 290 Address to store the starting address of the value. When using data type
 291 \fBDATA_TYPE_BOOLEAN\fR, the \fIval\fR argument is ignored.
 292 .RE
 293
 294 .sp
 295 .ne 2
 296 .na
 297 \fB\fInelem\fR\fR
 298 .ad
 299 .RS 9n
 300 Address to store the number of elements in value. Non-array data types have
 301 only one argument and \fInelem\fR is ignored.
 302 .RE
 303
 304 .sp
 305 .LP
 306 The argument order is \fIname\fR, \fItype\fR, [\fIval\fR], [\fInelem\fR].
 307 .sp
 308 .LP
 309 When using \fBNV_FLAG_NOENTOK\fR and no matching name-value pair is found, the
 310 memory pointed to by \fIval\fR and \fInelem\fR is not touched.
 311 .sp
 312 .LP
 313 These functions return \fB0\fR on success and an error value on failure.
 314 .SH ERRORS
 315 .sp
 316 .LP
 317 These functions fail under the following conditions.
 318 .sp
 319 .ne 2
 320 .na
 321 \fB\fB0\fR\fR
 322 .ad
 323 .RS 11n
 324 Success
 325 .RE
 326
 327 .sp
 328 .ne 2
 329 .na
 330 \fB\fBEINVAL\fR\fR
 331 .ad
 332 .RS 11n
 333 Invalid argument
 334 .RE
 335
 336 .sp
 337 .ne 2
 338 .na
 339 \fB\fBENOENT\fR\fR
 340 .ad
 341 .RS 11n
 342 No matching name-value pair found
 343 .RE
 344
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fBENOTSUP\fR\fR
 349 .ad
 350 .RS 11n
 351 Encode/decode method not supported
 352 .RE
 353
 354 .SH CONTEXT
 355 .sp
 356 .LP
 357 These functions can be called from user, interrupt, or kernel context.
 358 .SH ATTRIBUTES
 359 .sp
 360 .LP
 361 See \fBattributes\fR(5) for descriptions of the following attributes:
 362 .sp
 363
 364 .sp
 365 .TS
 366 box;
 367 c | c
 368 l | l .
 369 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 370 _
 371 Interface Stability     Committed
 372 .TE
 373
 374 .SH SEE ALSO
 375 .sp
 376 .LP
 377 \fBnvlist_alloc\fR(9F), \fBnvpair_type\fR(9F)
 378 .sp
 379 .LP
 380 \fIWriting Device Drivers\fR
 381 .sp
 382 .LP
 383 \fISTREAMS Programming Guide\fR