sstore_collection_alloc, sstore_collection_delete, sstore_collection_free, sstore_collection_id, sstore_collection_set_state, sstore_collection_update_ssid, sstore_collection_write - Interfaces to manage statistics store collections
cc [ flag... ] file... -lsstore [ library... ]
#include <libsstore.h>
sstore_collection_t sstore_collection_alloc(const char *id);
void sstore_collection_free(sstore_collection_t c_hdl);
sstore_err_t sstore_collection_set_state(
sstore_handle_t hdl, sstore_collection_t c_hdl,
sstore_collection_state_t state);
sstore_err_t sstore_collection_update_ssid(
sstore_handle_t hdl, sstore_collection_t c_hdl,
const char **ids, uint32_t id_count, boolean_t add);
sstore_err_t sstore_collection_write(sstore_handle_t hdl,
sstore_collection_t c_hdl);
sstore_err_t sstore_collection_delete(sstore_handle_t hdl,
sstore_collection_t c_hdl);
Statistics store identifier for the collection
Handle to a local collection object
Handle to libsstore
One of the following collection states:
Enables persistent recording for all the statistics store identifiers in the collection
Disables persistent recording for all the statistics store identifiers in the collection
Array of ssids
Total number of statistics store identifiers
Boolean flag specifying whether to add or remove statistics store identifiers
A collection is a named group of statistics store identifiers (ssids). It has a universally unique identifier (UUID), a state, an owner, and an optional custom name. The UUID uniquely identifies the collection. The state determines whether ssids in the collection are persistently recorded. The owner of a collection is the user who created the collection. The owner can give the collection a custom name that users can use instead of the UUID.
A collection can be referenced by either of the following two ssids.
The first collection ssid is based on its UUID and is formatted as follows:
//:class.collection//:collection.uuid/<UUID>
The second collection ssid exists only if the user gives the collection a custom name. This ssid is formatted as follows:
//:class.collection//:collection.name/[<OWNER>/][CUSTOM_NAME]
The [<OWNER>/] part is optional. If the OWNER is not specified then the user calling the libsstore API is assumed to be the owner and the collection is looked up in that user's profile.
For example, the ssid for a collection named col_bar created by user user_foo is formatted as follows:
//:class.collection//:collection.name/user_foo/col_bar
The following ssid is valid if the same user, user_foo, is also the caller:
//:class.collection//:collection.name/col_bar
The ssid used to refer to a collection in the statistics store namespace is called the collection ID to distinguish the collection ID from the ssids that are included in the collection. The collection ID can be passed as an element of the array of ssids, which are the ids argument to sstore_data_read(3SSTORE) and sstore_info_read(3SSTORE). The collection ID can also be passed as a pattern to sstore_namespace_list(3SSTORE).
sstore_collection_alloc() allocates and initializes a local collection object. The id argument is optional. The id argument must be passed to take any action on an existing collection or give a custom name to a new collection. If id is not NULL, then the ID is set in the local collection object and this is returned when sstore_collection_id(3SSTORE) is called for this collection object.
sstore_collection_free() frees the memory associated with given local collection object.
sstore_collection_set_state() sets the new collection state in the local collection object. The state change is not reflected in the statistics store until sstore_collection_write(3SSTORE) is called with this collection object.
sstore_collection_update_ssid() queues up an update to the corresponding collection in statistics store in the local collection object. The update is not reflected in the statistics store until sstore_collection_write(3SSTORE) is called with the given local collection object. The boolean add specifies whether the update is to add or remove the given IDs.
sstore_collection_write() writes all the updates in the local collection object to the corresponding collection in the statistics store. If no collection in the statistics store corresponds to the local collection object, then sstore_collection_write() creates a collection in statistics store with a new UUID. It also stores the collection ID (ssid used to refer to this collection) based on the UUID of this new collection in the local collection object. This collection ID can be retrieved later using sstore_collection_id(3SSTORE). If a custom collection ID was provided to sstore_collection_alloc(), then that ID can also be used to refer to this new collection.
sstore_collection_id() returns the collection ID set in the local collection object.
sstore_collection_delete() removes the corresponding collection and all of its references from the statistics store namespace.
Authorization is required for the following operation:
Client must have solaris.sstore.configure authorization.
Upon successful completion, sstore_collection_alloc() returns an sstore_collection_t. Otherwise, it returns NULL.
Upon successful completion, sstore_collection_set_state(), sstore_collection_update_ssid(), sstore_collection_write(), and sstore_collection_delete() return ESSTORE_OK. Otherwise, they return an error code, which is also cached in the given libsstore handle.
The sstore_collection_alloc() function fails if:
There is insufficient memory
The sstore_collection_update_ssid() function fails if:
Some arguments are invalid
The libsstore handle is invalid
No memory is available
The sstore_collection_set_state() function fails if:
Some arguments are invalid
The libsstore handle is invalid
The sstore_collection_write() function fails if:
One of the following reasons:
The collection object is valid.
The ssid format of the collection ID is invalid.
The ssid for the collection was in UUID format and it does not exist.
The libsstore handle is invalid
There is insufficient memory
The client is not authorized. For more information, see the sstore-security(7) man page
Failed to connect to the statistics store daemon
The sstore_collection_delete() function fails if:
One of the following reasons:
The collection object is invalid.
The ssid format of the collection ID is invalid
The libsstore handle is invalid
There is insufficient memory
The client is not authorized. For more information, see the sstore-security(7) man page
Failed to connect to the statistics store daemon
See attributes(7) for descriptions of the following attributes:
|
libsstore(3LIB), sstore_alloc(3SSTORE), sstore_err_action(3SSTORE), attributes(7), ssid(7), sstore-security(7)