Go to main content

man pages section 3: Extended Library Functions, Volume 4

Exit Print View

Updated: Thursday, June 13, 2019
 
 

sstore_range_free (3SSTORE)

Name

sstore_range_alloc, sstore_range_free, sstore_range_set_points, sstore_range_set_times, sstore_range_flags - Interfaces to allocate, initialize and free an sstore_range_t

Synopsis

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

     sstore_range_t sstore_range_alloc;

     void sstore_range_free(sstore_range_t range);

     sstore_range_t sstore_range_set_times(sstore_range_t range,
         uint64_t start_time, uint64_t end_time, uint64_t step);

     sstore_range_t sstore_range_set_points(sstore_range_t range,
         uint64_t start_time, uint64_t num_points);

     sstore_range_t sstore_range_flags(sstore_range_t range,
         uint64_t flags);

Parameters

range

libsstore range struct

start_time

Time in micro-seconds since epoch. SS_TIME_NOW can be used to define relative time ranges.

end_time

Time in micro-seconds since epoch. SS_TIME_NOW can be used to define relative time ranges.

step

granularity in seconds

num_points

number of data points

flags

ssid lookup resolution flags

Description

sstore_range_alloc() allocates a sstore_range_t.

sstore_range_free() frees the range.

sstore_range_set_times() initializes the range with the given time range values. If the range argument is NULL, then it also allocates a new sstore_range_t, otherwise it just reuses the given sstore_range_t.

The time range defined can be absolute or relative.

If neither start_time nor end_time are SS_TIME_NOW, then the time range is absolute and it represents a time range from start_time to end_time inclusive.

If end_time is SS_TIME_NOW, then the time range is relative and it represents a time range from start_time to the most recent data point for the given ssids.

If start_time is SS_TIME_NOW and end_time is not SS_TIME_NOW, then the time range is relative and it represents a time range from (Now - end_time) to Now. In this case, end_time should be in units of seconds.

step specifies the granularity (in seconds) between data points, and will force the distance between timestamps to be exactly step through interpolation. The starting point will always be the start-time of the range. If this behavior is not desired, then a step of 0 should be passed to avoid interpolation. In the step = 0 scenario, no guarantees are made about the distance between data points in time.

sstore_range_set_points() initializes the range with the given range of data points. If the range argument is NULL, then it also allocates a new sstore_range_t, otherwise it just reuses the given sstore_range_t.

The range of data points represents a fixed number of data points relative to a time stamp.

If start_time is SS_TIME_NOW and num_points is -n, then the range of data points it represents is the last n data points from Now.

If start_time is not SS_TIME_NOW and num_points is +n, then the range of data points it represents are the next n data points after start_time. sstore_range_flags() initializes the ssid lookup resolution flags. By default, wildcards within ssids only resolve statistics and events that have a stability of stable and are browsable (refer to ssid-metadata(7) for more information). To override this behavior, the following flags are provided:

SS_SHOW_UNSTABLE

Allow wildcards to match unstable ssids.

SS_SHOW_UNBROWSABLE

Allow wildcards to match unbrowsable ssids.

Return Values

Upon successful completion, sstore_range_alloc(), sstore_range_set_times() and sstore_range_set_points() returns a non-NULL address to an sstore_range_t. Otherwise, it returns NULL.

Errors

The sstore_range_alloc(), sstore_range_set_times(), sstore_range_set_points(), and sstore_range_flags() functions will fail if:

ENOMEM

There is insufficient memory.

Attributes

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

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
Safe

See Also

perror(3C), libsstore(3LIB), attributes(7), ssid(7)