Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sstore_namespace_list (3SSTORE)

Name

sstore_namespace_list, sstore_namespace_iter_next - Interface to search the namespace and explore system topology

Synopsis

cc [ flag... ] file... -lsstore [ library... ]
#include <libsstore.h>

sstore_err_t sstore_namespace_list(sstore_handle_t hdl,
   const char **ids, uint32_t id_count, sstore_range_t range,
	 sstore_iter_t *iterp);

sstore_err_t sstore_namespace_iter_next(sstore_handle_t hdl,
   sstore_iter_t iter, char **idp, uint64_t *start_tsp,
	 uint64_t *end_tsp)

Parameters

hdl

Handle to libsstore

ids

Array of stats store identifiers

id_count

Total number of statistics store identifiers

range

Time range or data range

Passing NULL for range implies:

  • start-time = SS_TIME_NOW

  • end-time = SS_TIME_NOW

  • step = 1

iterp

Address to store the starting address of the iterator.

Description

sstore_namespace_list() retrieves all of the matching identifiers. A resource is only shown if it is present during the given time range. The retrieved data is returned in the form of an iterator that can be used to read the data records. Once all the data records have been read from the iterator, the iterator should be freed using sstore_iter_free(3SSTORE).

The sstore_namespace_iter_next retrieves the next record in the iteration. Each record consists of an ssid and a time stamp. The reference pointers passed to this call are populated if the call succeeds. The identifier and time stamp, are populated on success do not need to be freed. They are freed on the next call to sstore_namespace_iter_next.

The given identifiers can use the wildcard character, * to match anything in the identifier except the reserved character combination, //:. So, a search pattern such as //:class.cpu//:res.id/* on a system that has cpu 0, 1, 2 and 3 online during the given time range returns the following identifiers:

//:class.cpu//:res.id/0
//:class.cpu//:res.id/1
//:class.cpu//:res.id/2
//:class.cpu//:res.id/3

A search pattern such as //:class.prset//:res.id/*//:class.cpu/res.id/* on a system that has two processor sets, 0, and 1 with cpu 0, and 1 being in processor set 0 and cpu 2, and 3 being in processor set 1 during the given time range returns the following identifiers:

//:class.prset//:res.id/0//:class.cpu/res.id/0
//:class.prset//:res.id/0//:class.cpu/res.id/1
//:class.prset//:res.id/1//:class.cpu/res.id/2
//:class.prset//:res.id/1//:class.cpu/res.id/3

The following search pattern will return an array with the identifiers for all the statistics that can be captured for cpu 0, 1, 2 and 3 if the start time and end time specified in the range are both SS_TIME_NOW, otherwise the pattern will return an array with the identifiers for all the statistics that were being captured during that time range:

//:class.cpu//:res.id///:s.[0:3]//:stat.*

Return Values

Upon successful completion, sstore_namespace_list() and sstore_namespace_iter_next() return ESSTORE_OK. Otherwise, they return an error code, which is also cached in hdl.

Errors

The sstore_namespace_list() function will fail if:

ESSTORE_ARG_INVALID

Some arguments are invalid.

ESSTORE_CONNECTION_BROKEN

The connection to the Statistics Store failed or was interrupted.

ESSTORE_HANDLE_INVALID

The handle is invalid

ESSTORE_NOMEM

No memory is available.

ESSTORE_RETRY

Statistics store is busy. Please retry after some time.

ESSTORE_TOO_BIG

The total size of the result for the requested operation is larger than the maximum size limit set in hdl.

The sstore_data_iter_next() function will fail if:

ESSTORE_ARG_INVALID

Some arguments are invalid.

ESSTORE_HANDLE_INVALID

The handle is invalid

ESSTORE_ITER_DONE

No more records left to iterate.

Warnings

sstore_namespace_list() can throw up the following warnings:

SS_WARN_INVALID

An identifier is invalid.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Safe

See Also

libsstore(3LIB), attributes(7)