Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
This information is Copyright 2007 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
nvlist extensions
1.2. Name of Document Author/Supplier:
Author: Eric Schrock
1.3 Date of This Document:
18 October, 2007
4. Technical Description
This case extends the existing nvpair interfaces wiith two new
functions, nvlist_exists() and nvlist_lookup_nvpair(). The interfaces
are Committed and the binding is patch.
A. INTRODUCTION
The nvpair interfaces shared by the kernel and libnvpair(3LIB) have been
gradually expanded over the years to support new types and expanded
functionality. There are two cases where the current interfaces fall
short when dealing with lists with variable content.
When using nvlists that allow for optional types, it is desirable to
lookup a nvpair only by name, and then take action based on its type.
The current interfaces require that the consumer always know the type a
priori.
When using nvlists with non-unique name or types, it is sometimes
desirable to determine simply whether an nvpair exists at all,
regardless of type.
Both these problems can be solved by iterating over the list by hand,
but this is cumbersome. This functionality should be provided by the
nvpair interfaces.
B. DESCRIPTION
This case introduces new interfaces in <sys/nvpair.h>, available via
libnvpair and the kernel DDI. A new manpage for nvlist_lookup_nvpair()
will be introduced, and will include both new functions. As with other
nvpair interfaces, libnvpair(3LIB) will be updated to include the new
functions, and the manpage will be available as either
nvlist_lookup_nvpair(3NVPAIR) or nvlist_lookup_nvpair(9F).
NAME
nvlist_lookup_nvpair, nvlist_exists - lookup named pairs
SYNOPSIS
cc [ flag... ] file... -lnvpair [ library... ]
#include <libnvpair.h>
int nvlist_lookup_nvpair(nvlist_t *nvl, const char *name,
nvpair_t **nvp);
boolean_t nvlist_exists(nvlist_t *nvl, const char *name);
DESCRIPTION
These functions lookup nvpairs regardless of type.
nvlist_lookup_nvpair()
This function returns the nvpair with the matching name,
regardless of type. It is valid only for lists
allocated with NV_UNIQUE_NAME (see nvlist_alloc(3nvpair)).
nvlist_exists()
This functions returns success if any nvpair exists with
the given name. It is valid for all types of lists.
RETURN VALUES
nvlist_exists() returns B_TRUE if a nvpair with the given
name exists, B_FALSE otherwise.
nvlist_lookup_nvpair() returns 0 on success and an error
value on failure.
ERRORS
The nvlist_lookup_nvpair() function will fail if:
EINVAL There is an invalid argument
ENOENT No matching name-value pair is found
ENOTSUP The list was not allocated with NV_UNIQUE_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), nvpair_type(3NVPAIR), attributes(5)
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
OS/Net
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
