I am self-sponsoring this case.
The case adds two committed interfaces to libstmf(3LIB). The binding is
patch as is the original case PSARC/2007/523.
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:
libstmf enhancement for provider data
1.2. Name of Document Author/Supplier:
Author: John Forte
1.3 Date of This Document:
09 July, 2008
4. Technical Description
SUMMARY
This case adds two new interfaces to libstmf (PSARC 2007/523) for managing
provider data for concurrent clients.
PROBLEM
There are two existing interfaces (stmfGetProviderData(3STMF),
stmfSetProviderData(3STMF)) that enable a client to get and set provider
data. Unfortunately there is no mechanism by which a client issuing a
set operation can determine whether the set is in conflict with another
client issuing a set operation on the same provider data, i.e. a set of
stale data.
PROPOSED SOLUTION
Two new interfaces (stmfGetProviderDataProt(),
stmfSetProviderDataProt()) provide the caller with a token to be
retrieved on "get" and passed on "set" that will enable the client to
determine on "set" whether the data retrieved from the get matching
the passed token is not stale. If the token is no longer valid, the
call to "set" will fail with STMF_ERROR_PROV_DATA_STALE. Alternately,
the token may be set to NULL by the caller for the "get" or "set" which
will effectively revert these calls to stmfGetProviderData() and
stmfSetProviderData() respectively. This case will deprecate
stmfGetProviderData(3STMF) and stmfSetProviderData(3STMF).
MANPAGE ADDITIONS
stmfGetProviderDataProt(3STMF):
NAME
stmfGetProviderDataProt - retrieve the data for the specified
provider
SYNOPSIS
cc [ flag... ] file... -lstmf [ library... ]
#include <libstmf.h>
int stmfGetProviderDataProt(char *providerName, nvlist_t **nvl,
int providerType, uint64_t *token);
PARAMETERS
providerName The name of the provider for which data is
being retrieved.
nvl A pointer to a pointer to an nvlist_t. On success,
this will contain the nvlist retrieved. Caller is
responsible for freeing the returned nvlist by
calling nvlist_free(3NVPAIR).
providerType The value for this parameter must be either
STMF_LU_PROVIDER_TYPE or
STMF_PORT_PROVIDER_TYPE.
token A pointer to a uint64_t allocated by the caller.
On success, this will contain a token for the
returned data that can be used in a call to
stmfSetProviderDataProt(3STMF) to ensure that
the data returned in this call is not stale.
If this value is NULL, the token will be
ignored.
DESCRIPTION
The stmfGetProviderDataProt() function retrieves the data for the
specified provider.
RETURN VALUES
The following values are returned:
STMF_ERROR_NOMEM The library was unable to allocate sufficient
memory to return the data.
STMF_STATUS_SUCCESS The API call was successful.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
_____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libstmf(3LIB), nvlist_free(3NVPAIR), attributes(5)
stmfSetProviderDataProt(3STMF):
NAME
stmfSetProviderDataProt - retrieve the data for the specified
provider
SYNOPSIS
cc [ flag... ] file... -lstmf [ library... ]
#include <libstmf.h>
int stmfSetProviderData(char *providerName, nvlist_t **nvl,
int providerType, uint64_t *token);
PARAMETERS
providerName The name of the provider for which data is
being retrieved.
nvl A pointer to a an nvlist_t containing the nvlist
to be set.
providerType The value for this parameter must be either
STMF_LU_PROVIDER_TYPE or
STMF_PORT_PROVIDER_TYPE.
token A pointer to a uint64_t that contains the value
returned from a successful call to
stmfGetProviderDataProt(3STMF). If this argument
is NULL, the token is ignored. Otherwise, the
token will be verified against the current data.
If the token represents stale data, the call
fails.
On success, this will contain the new token for the
data being set and can be used in subsequent
calls to stmfSetProviderData. On failure the
contents are undefined.
DESCRIPTION
The stmfSetProviderDataProt() function sets the data for the
specified provider.
RETURN VALUES
The following values are returned:
STMF_ERROR_NOMEM The library was unable to allocate sufficient
memory to return the data.
STMF_ERROR_PROV_DATA_STALE
The token value represents stale data.
STMF_STATUS_SUCCESS The API call was successful.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
_____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed |
|_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
libstmf(3LIB), nvlist_free(3NVPAIR), attributes(5)
stmfGetProviderData(3STMF)
.
.
.
NOTES
This interface is deprecated in favor of
stmfGetProviderDataProt(3STMF) and may be removed in a future
revision of libstmf(3LIB).
stmfGetProviderData(3STMF)
.
.
.
NOTES
This interface is deprecated in favor of
stmfSetProviderDataProt(3STMF) and may be removed in a future
revision of libstmf(3LIB).
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
NWS
6.5. ARC review type: Automatic
6.6. ARC Exposure: open
