Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sstore_collection_alloc (3SSTORE)

Name

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

Synopsis

     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);

Parameters

id

Statistics store identifier for the collection

c_hdl

Handle to a local collection object

hdl

Handle to libsstore

state

One of the following collection states:

SSTORE_COLLECTION_STATE_ENABLED

Enables persistent recording for all the statistics store identifiers in the collection

SSTORE_COLLECTION_STATE_DISABLED

Disables persistent recording for all the statistics store identifiers in the collection

ids

Array of ssids

id_count

Total number of statistics store identifiers

add

Boolean flag specifying whether to add or remove statistics store identifiers

Description

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.

Authorizations

Authorization is required for the following operation:

Update another user's collection

Client must have solaris.sstore.configure authorization.

Return Values

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.

Errors

The sstore_collection_alloc() function fails if:

ENOMEM

There is insufficient memory

The sstore_collection_update_ssid() function fails if:

ESSTORE_ARG_INVALID

Some arguments are invalid

ESSTORE_HANDLE_INVALID

The libsstore handle is invalid

ESSTORE_NOMEM

No memory is available

The sstore_collection_set_state() function fails if:

ESSTORE_ARG_INVALID

Some arguments are invalid

ESSTORE_HANDLE_INVALID

The libsstore handle is invalid

The sstore_collection_write() function fails if:

ESSTORE_ARG_INVALID

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.

ESSTORE_HANDLE_INVALID

The libsstore handle is invalid

ESSTORE_NOMEM

There is insufficient memory

ESSTORE_UNAUTHORIZED

The client is not authorized. For more information, see the sstore-security(7) man page

ESSTORE_CONNECTION_FAILED

Failed to connect to the statistics store daemon

The sstore_collection_delete() function fails if:

ESSTORE_ARG_INVALID

One of the following reasons:

  • The collection object is invalid.

  • The ssid format of the collection ID is invalid

ESSTORE_HANDLE_INVALID

The libsstore handle is invalid

ESSTORE_NOMEM

There is insufficient memory

ESSTORE_UNAUTHORIZED

The client is not authorized. For more information, see the sstore-security(7) man page

ESSTORE_CONNECTION_FAILED

Failed to connect to the statistics store daemon

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Safe

See Also

libsstore(3LIB), sstore_alloc(3SSTORE), sstore_err_action(3SSTORE), attributes(7), ssid(7), sstore-security(7)