nvlist_lookup_boolean.3nvpair revision c10c16dec587a0662068f6e2991c29ed3a9db943
te
Copyright (c) 2008, 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]
nvlist_lookup_boolean 3NVPAIR "1 Aug 2008" "SunOS 5.11" "Name-value Pair Library Functions"
NAME
nvlist_lookup_boolean, nvlist_lookup_boolean_value, nvlist_lookup_byte, nvlist_lookup_int8, nvlist_lookup_uint8, nvlist_lookup_int16, nvlist_lookup_uint16, nvlist_lookup_int32, nvlist_lookup_uint32, nvlist_lookup_int64, nvlist_lookup_uint64, nvlist_lookup_double, nvlist_lookup_string, nvlist_lookup_nvlist, nvlist_lookup_boolean_array, nvlist_lookup_byte_array, nvlist_lookup_int8_array, nvlist_lookup_uint8_array, nvlist_lookup_int16_array, nvlist_lookup_uint16_array, nvlist_lookup_int32_array, nvlist_lookup_uint32_array, nvlist_lookup_int64_array, nvlist_lookup_uint64_array, nvlist_lookup_nvlist_array, nvlist_lookup_string_array, nvlist_lookup_pairs - match name and type indicated by the interface name and retrieve data value
SYNOPSIS

cc [ flag... ] file... -lnvpair [ library... ]
#include <libnvpair.h>

int nvlist_lookup_boolean(nvlist_t *nvl, const char *name);

int nvlist_lookup_boolean_value(nvlist_t *nvl,
 const char *name, boolean_t *val);

int nvlist_lookup_byte(nvlist_t *nvl, const char *name,
 uchar_t *val);

int nvlist_lookup_int8(nvlist_t *nvl, const char *name,
 int8_t *val);

int nvlist_lookup_uint8(nvlist_t *nvl, const char *name,
 uint8_t *val);

int nvlist_lookup_int16(nvlist_t *nvl, const char *name,
 int16_t *val);

int nvlist_lookup_uint16(nvlist_t *nvl, const char *name,
 uint16_t *val);

int nvlist_lookup_int32(nvlist_t *nvl, const char *name,
 int32_t *val);

int nvlist_lookup_uint32(nvlist_t *nvl, const char *name,
 uint32_t *val);

int nvlist_lookup_int64(nvlist_t *nvl, const char *name,
 int64_t *val);

int nvlist_lookup_uint64(nvlist_t *nvl, const char *name,
 uint64_t *val);

int nvlist_lookup_double(nvlist_t *nvl, const char *name,
 double *val);

int nvlist_lookup_string(nvlist_t *nvl, const char *name,
 char **val);

int nvlist_lookup_nvlist(nvlist_t *nvl, const char *name,
 nvlist_t **val);

int nvlist_lookup_boolean_array(nvlist_t *nvl, const char *name,
 boolean_t **val, uint_t *nelem);

int nvlist_lookup_byte_array(nvlist_t *nvl, const char *name,
 uchar_t **val, uint_t *nelem);

int nvlist_lookup_int8_array(nvlist_t *nvl, const char *name,
 int8_t **val, uint_t *nelem);

int nvlist_lookup_uint8_array(nvlist_t *nvl, const char *name,
 uint8_t **val, uint_t *nelem);

int nvlist_lookup_int16_array(nvlist_t *nvl, const char *name,
 int16_t **val, uint_t *nelem);

int nvlist_lookup_uint16_array(nvlist_t *nvl, const char *name,
 uint16_t **val, uint_t *nelem);

int nvlist_lookup_int32_array(nvlist_t *nvl, const char *name,
 int32_t **val, uint_t *nelem);

int nvlist_lookup_uint32_array(nvlist_t *nvl, const char *name,
 uint32_t **val, uint_t *nelem);

int nvlist_lookup_int64_array(nvlist_t *nvl, const char *name,
 int64_t **val, uint_t *nelem);

int nvlist_lookup_uint64_array(nvlist_t *nvl, const char *name,
 uint64_t **val, uint_t *nelem);

int nvlist_lookup_string_array(nvlist_t *nvl, const char *name,
 char ***val, uint_t *nelem);

int nvlist_lookup_nvlist_array(nvlist_t *nvl, const char *name,
 nvlist_t ***val, uint_t *nelem);

int nvlist_lookup_pairs(nvlist_t *nvl, int flag...);
PARAMETERS

nvl

The nvlist_t to be processed.

name

Name of the name-value pair to search.

nelem

Address to store the number of elements in value.

val

Address to store the starting address of the value.

flag

Specify bit fields defining lookup behavior:

NV_FLAG_NOENTOK

The retrival function will not fail if no matching name-value pair is found.

DESCRIPTION

These functions find the nvpair (name-value pair) that matches the name and type as indicated by the interface name. If one is found, nelem and val are modified to contain the number of elements in value and the starting address of data, respectively.

These functions work for nvlists (lists of name-value pairs) allocated with NV_UNIQUE_NAME or NV_UNIQUE_NAME_TYPE specified in nvlist_alloc(3NVPAIR). If this is not the case, the function returns ENOTSUP because the list potentially contains multiple nvpairs with the same name and type.

Multiple threads can simultaneously read the same nvlist_t but only one thread can actively change a given nvlist_t at a time. The caller is responsible for the synchronization.

All memory required for storing the array elements, including string value, are managed by the library. References to such data remain valid until nvlist_free() is called on nvl.

The nvlist_lookup_pairs() function retrieves a set of nvpairs. The arguments are a null-terminated list of pairs (data type DATA_TYPE_BOOLEAN), triples (non-array data types) or quads (array data types). The interpretation of the arguments depends on the value of type (see nvpair_type(3NVPAIR)) as follows:

name

Name of the name-value pair to search.

type

Data type (see nvpair_type(3NVPAIR)).

val

Address to store the starting address of the value. When using data type DATA_TYPE_BOOLEAN, the val argument is omitted.

nelem

Address to store the number of elements in value. Non-array data types have only one argument and nelem is omitted.

The order of the arguments is name, type, [val], [nelem].

When using NV_FLAG_NOENTOK and no matching name-value pair is found, the memory pointed to by val and nelem is left untouched.

RETURN VALUES

These functions return 0 on success and an error value on failure.

ERRORS

These functions will fail if:

EINVAL

There is an invalid argument.

ENOENT

No matching name-value pair is found

ENOTSUP

An encode/decode method is not supported.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPEATTRIBUTE VALUE
Interface StabilityCommitted
MT-LevelMT-Safe
SEE ALSO

libnvpair(3LIB), nvlist_alloc(3NVPAIR), nvpair_type(3NVPAIR), attributes(5)