Template Version: @(#)sac_nextcase 1.66 04/17/08 SMI
This information is Copyright 2008 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
Extending libnvpair for type double
1.2. Name of Document Author/Supplier:
Author: Robert Johnston
1.3 Date of This Document:
08 July, 2008
4. Technical Description
The key components of Solaris FMA (e.g.the fault manager and libtopo)
maintain their property and state information using libnvpair. As part of the
work to develop a sensor abstraction layer for FMA, we require the ability
to represent analog sensor readings, which are typically expressed as
floating point values. Therefore it has become necessary to extend libnvpair
to allow floating point values.
This case seeks to extend libnvpair with three new interfaces to <libnvpair.h>:
int nvlist_add_double(nvlist_t *nvl, const char *name, double val);
int nvlist_lookup_double(nvlist_t *nvl , const char *name, double *);
int nvpair_value_double(nvpair_t *nvpair, double *val);
Because use of floating point types is discouraged in the kernel, and all of
the FMA components that will be consuming these new interfaces live in
userland, they will be made available via libnvpair but not in the kernel DDI.
Preprocessor guards will be used to ensure the new code is not compiled
into the kernel.
The libnvpair(3LIB) man page will be updated to include the new functions.
The man pages for the nvlist_add/lookup_* and nvpair_value_* functions all
link to one of the following three man pages, respectively, which
includes content that covers the various forms of the interfaces for all
of the different data types:
nvlist_add_boolean(3NVPAIR)
nvlist_lookup_boolean(3NVPAIR)
nvpair_value_byte(3NVPAIR)
These three man pages will be updated to include the new interfaces for
DATA_TYPE_DOUBLE. The updated man page conent is included below.
Name-value Pair Library Functions nvlist_add_boolean(3NVPAIR)
NAME
nvlist_add_boolean, nvlist_add_boolean_value,
nvlist_add_byte, nvlist_add_int8, nvlist_add_uint8,
nvlist_add_int16, nvlist_add_uint16, nvlist_add_int32,
nvlist_add_uint32, nvlist_add_int64, nvlist_add_uint64,
nvlist_add_double, nvlist_add_string, nvlist_add_nvlist,
nvlist_add_nvpair, nvlist_add_boolean_array,
nvlist_add_byte_array, nvlist_add_int8_array,
nvlist_add_uint8_array, nvlist_add_int16_array,
nvlist_add_uint16_array, nvlist_add_int32_array,
nvlist_add_uint32_array, nvlist_add_int64_array,
nvlist_add_uint64_array, nvlist_add_string_array,
nvlist_add_nvlist_array - add new name-value pair to nvlist_t
SYNOPSIS
cc [ flag... ] file... -lnvpair [ library... ]
#include <libnvpair.h>
int nvlist_add_boolean(nvlist_t *nvl, const char *name);
int nvlist_add_boolean_value(nvlist_t *nvl,
const char *name, boolean_t val);
int nvlist_add_byte(nvlist_t *nvl, const char *name,
uchar_t val);
int nvlist_add_int8(nvlist_t *nvl, const char *name,
int8_t val);
int nvlist_add_uint8(nvlist_t *nvl, const char *name,
uint8_t val);
int nvlist_add_int16(nvlist_t *nvl, const char *name,
int16_t val);
int nvlist_add_uint16(nvlist_t *nvl, const char *name,
uint16_t val);
int nvlist_add_int32(nvlist_t *nvl, const char *name,
int32_t val);
int nvlist_add_uint32(nvlist_t *nvl, const char *name,
uint32_t val);
int nvlist_add_int64(nvlist_t *nvl, const char *name,
int64_t val);
int nvlist_add_uint64(nvlist_t *nvl, const char *name,
uint64_t val);
int nvlist_add_double(nvlist_t *nvl, const char *name,
double val);
int nvlist_add_string(nvlist_t *nvl, const char *name,
const char *val);
int nvlist_add_nvlist(nvlist_t *nvl, const char *name,
nvlist_t *val);
int nvlist_add_nvpair(nvlist_t *nvl, nvpair_t *nvp);
int nvlist_add_boolean_array(nvlist_t *nvl, const char *name,
boolean_t *val, uint_t nelem);
int nvlist_add_byte_array(nvlist_t *nvl, const char *name,
uchar_t *val, uint_t nelem);
int nvlist_add_int8_array(nvlist_t *nvl, const char *name,
int8_t *val, uint_t nelem);
int nvlist_add_uint8_array(nvlist_t *nvl, const char *name,
uint8_t *val, uint_t nelem);
int nvlist_add_int16_array(nvlist_t *nvl, const char *name,
int16_t *val, uint_t nelem);
int nvlist_add_uint16_array(nvlist_t *nvl, const char *name,
uint16_t *val, uint_t nelem);
int nvlist_add_int32_array(nvlist_t *nvl, const char *name,
int32_t *val, uint_t nelem);
int nvlist_add_uint32_array(nvlist_t *nvl, const char *name,
uint32_t *val, uint_t nelem);
int nvlist_add_int64_array(nvlist_t *nvl, const char *name,
int64_t *val, uint_t nelem);
int nvlist_add_uint64_array(nvlist_t *nvl, const char *name,
uint64_t *val, uint_t nelem);
int nvlist_add_string_array(nvlist_t *nvl, const char *name,
char *const *val, uint_t nelem);
int nvlist_add_nvlist_array(nvlist_t *nvl, const char *name,
nvlist_t **val, uint_t nelem);
PARAMETERS
nvl The nvlist_t (name-value pair list) to be pro-
cessed.
nvp The nvpair_t (name-value pair) to be processed.
name Name of the nvpair (name-value pair).
nelem Number of elements in value (that is, array size).
val Value or starting address of the array value.
DESCRIPTION
These functions add a new name-value pair to an nvlist_t.
The uniqueness of nvpair name and data types follows the
nvflag argument specified for nvlist_alloc(). See
nvlist_alloc(3NVPAIR).
If NV_UNIQUE_NAME was specified for nvflag, existing nvpairs
with matching names are removed before the new nvpair is
added.
If NV_UNIQUE_NAME_TYPE was specified for nvflag, existing
nvpairs with matching names and data types are removed
before the new nvpair is added.
If neither was specified for nvflag, the new nvpair is
unconditionally added at the end of the list. The library
preserves the order of the name-value pairs across packing,
unpacking, and duplication.
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.
The nvlist_add_boolean() function is deprecated. The
nvlist_add_boolean_value() function should be used instead.
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.
ENOMEM There is insufficient memory.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|____________________________|______________________________|
| Interface Stability | Evolving |
|____________________________|______________________________|
| MT-Level | MT-Safe |
|____________________________|______________________________|
SEE ALSO
libnvpair(3LIB), attributes(5)
Name-value Pair Library Functions nvlist_lookup_boolean(3NVPAIR)
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 *);
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 speci-
fied in nvlist_alloc(). (See 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, includ-
ing 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 attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|____________________________|______________________________|
| Interface Stability | Evolving |
|____________________________|______________________________|
| MT-Level | MT-Safe |
|____________________________|______________________________|
SEE ALSO
libnvpair(3LIB), nvpair_type(3NVPAIR), attributes(5)
Name-value Pair Library Functions nvpair_value_byte(3NVPAIR)
NAME
nvpair_value_byte, nvpair_value_boolean_value,
nvpair_value_int8, nvpair_value_uint8, nvpair_value_int16,
nvpair_value_uint16, nvpair_value_int32,
nvpair_value_uint32, nvpair_value_int64,
nvpair_value_uint64, nvpair_value_double,
nvpair_value_string, nvpair_value_nvlist,
nvpair_value_boolean_array, nvpair_value_byte_array,
nvpair_value_int8_array, nvpair_value_uint8_array,
nvpair_value_int16_array, nvpair_value_uint16_array,
nvpair_value_int32_array, nvpair_value_uint32_array,
nvpair_value_int64_array, nvpair_value_uint64_array,
nvpair_value_string_array,
nvpair_value_nvlist_array - retrieve value from a name-value
pair
SYNOPSIS
cc [ flag... ] file... -lnvpair [ library... ]
#include <libnvpair.h>
int nvpair_value_byte(nvpair_t *nvpair, uchar_t *val);
int nvpair_value_boolean_value(nvpair_t *nvpair,
boolean_t *val);
int nvpair_value_int8(nvpair_t *nvpair, int8_t *val);
int nvpair_value_uint8(nvpair_t *nvpair, uint8_t *val);
int nvpair_value_int16(nvpair_t *nvpair, int16_t *val);
int nvpair_value_uint16(nvpair_t *nvpair, uint16_t *val);
int nvpair_value_int32(nvpair_t *nvpair, int32_t *val);
int nvpair_value_uint32(nvpair_t *nvpair, uint32_t *val);
int nvpair_value_int64(nvpair_t *nvpair, int64_t *val);
int nvpair_value_uint64(nvpair_t *nvpair, uint64_t *val);
int nvpair_value_double(nvpair_t *nvpair, double *val);
int nvpair_value_string(nvpair_t *nvpair, char **val);
int nvpair_value_nvlist(nvpair_t *nvpair, nvlist_t **val);
int nvpair_value_boolean_array(nvpair_t *nvpair,
boolean_t **val, uint_t *nelem);
int nvpair_value_byte_array(nvpair_t *nvpair, uchar_t **val,
uint_t *nelem);
int nvpair_value_int8_array(nvpair_t *nvpair, int8_t **val,
uint_t *nelem);
int nvpair_value_uint8_array(nvpair_t *nvpair, uint8_t **val,
uint_t *nelem);
int nvpair_value_int16_array(nvpair_t *nvpair, int16_t **val,
uint_t *nelem);
int nvpair_value_uint16_array(nvpair_t *nvpair,
uint16_t **val, uint_t *nelem);
int nvpair_value_int32_array(nvpair_t *nvpair,
int32_t **val, uint_t *nelem);
int nvpair_value_uint32_array(nvpair_t *nvpair,
uint32_t **val, uint_t *nelem);
int nvpair_value_int64_array(nvpair_t *nvpair,
int64_t **val, uint_t *nelem);
int nvpair_value_uint64_array(nvpair_t *nvpair,
uint64_t **val, uint_t *nelem);
int nvpair_value_string_array(nvpair_t *nvpair,
char ***val, uint_t *nelem);
int nvpair_value_nvlist_array(nvpair_t *nvpair,
nvlist_t ***val, uint_t *nelem);
PARAMETERS
nvpair Name-value pair to be processed.
nelem Address to store the number of elements in value.
val Address to store the value or the starting address
of the array value.
DESCRIPTION
These functions retrieve the value of nvpair. The data type
of nvpair must match the interface name for the call to be
successful.
There is no nvpair_value_boolean(); the existence of the
name implies the value is true.
For array data types, including string, the memory contain-
ing the data is managed by the library and references to the
value remains valid until nvlist_free() is called on the
nvlist_t from which nvpair is obtained. See
nvlist_free(3NVPAIR).
The value of an nvpair may not be retrieved after the nvpair
has been removed from or replaced in an nvlist. Replacement
can occur during pair additions to nvlists created with
NV_UNIQUE_NAME_TYPE and NV_UNIQUE_NAME. See
nvlist_alloc(3NVPAIR).
RETURN VALUES
These functions return 0 on success and an error value on
failure.
ERRORS
These functions will fail if:
EINVAL Either one of the arguments is NULL or the type of
nvpair does not match the function name.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|____________________________|______________________________|
| Interface Stability | Evolving |
|____________________________|______________________________|
| MT-Level | MT-Safe |
|____________________________|______________________________|
SEE ALSO
libnvpair(3LIB), nvlist_alloc(3NVPAIR), attributes(5)
These interfaces are Committed and seek patch binding.
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
