Timespec Utility APIs

Functions
static bool	timespec_is_valid (const struct timespec *ts)
	Check if a timespec is valid.
static bool	timespec_normalize (struct timespec *ts)
	Normalize a timespec so that the tv_nsec field is in valid range.
static bool	timespec_add (struct timespec *a, const struct timespec *b)
	Add one timespec to another.
static bool	timespec_negate (struct timespec *ts)
	Negate a timespec object.
static bool	timespec_sub (struct timespec *a, const struct timespec *b)
	Subtract one timespec from another.
static int	timespec_compare (const struct timespec *a, const struct timespec *b)
	Compare two timespec objects.
static bool	timespec_equal (const struct timespec *a, const struct timespec *b)
	Check if two timespec objects are equal.

Detailed Description

Function Documentation

timespec_add()

static bool timespec_add ( struct timespec *  a, const struct timespec *  b  )

inlinestatic

#include <include/zephyr/sys/timeutil.h>

Add one timespec to another.

This function sums the two timespecs pointed to by a and b and stores the result in the timespce pointed to by a.

If the operation would result in integer overflow, return value is false.

Note

a and b must be non-NULL and normalized.

Parameters

a	the timespec which is added to
b	the timespec to be added

Returns

true if the operation was successful, otherwise false.

timespec_compare()

static int timespec_compare ( const struct timespec *  a, const struct timespec *  b  )

inlinestatic

#include <include/zephyr/sys/timeutil.h>

Compare two timespec objects.

This function compares two timespec objects pointed to by a and b.

Note

a and b must be non-NULL and normalized.

Parameters

a	the first timespec to compare
b	the second timespec to compare

Returns

-1, 0, or +1 if a is less than, equal to, or greater than b, respectively.

timespec_equal()

static bool timespec_equal ( const struct timespec *  a, const struct timespec *  b  )

inlinestatic

#include <include/zephyr/sys/timeutil.h>

Check if two timespec objects are equal.

This function checks if the two timespec objects pointed to by a and b are equal.

Note

a and b must be non-NULL are not required to be normalized.

Parameters

a	the first timespec to compare
b	the second timespec to compare

Returns

true if the two timespec objects are equal, otherwise false.

timespec_is_valid()

static bool timespec_is_valid ( const struct timespec *  ts )

inlinestatic

#include <include/zephyr/sys/timeutil.h>

Check if a timespec is valid.

Check if a timespec is valid (i.e. normalized) by ensuring that the tv_nsec field is in the range [0, NSEC_PER_SEC-1].

Note

ts must not be NULL.

Parameters

ts	the timespec to check

Returns

true if the timespec is valid, otherwise false.

timespec_negate()

static bool timespec_negate ( struct timespec *  ts )

inlinestatic

#include <include/zephyr/sys/timeutil.h>

Negate a timespec object.

Negate the timespec object pointed to by ts and store the result in the same memory location.

If the operation would result in integer overflow, return value is false.

Parameters

ts	The timespec object to negate.

Returns

true of the operation is successful, otherwise false.

timespec_normalize()

static bool timespec_normalize ( struct timespec *  ts )

inlinestatic

#include <include/zephyr/sys/timeutil.h>

Normalize a timespec so that the tv_nsec field is in valid range.

Normalize a timespec by adjusting the tv_sec and tv_nsec fields so that the tv_nsec field is in the range [0, NSEC_PER_SEC-1]. This is achieved by converting nanoseconds to seconds and accumulating seconds in either the positive direction when tv_nsec > NSEC_PER_SEC, or in the negative direction when tv_nsec < 0.

In pseudocode, normalization can be done as follows:

if ts.tv_nsec >= NSEC_PER_SEC:
    sec = ts.tv_nsec / NSEC_PER_SEC
    ts.tv_sec += sec
    ts.tv_nsec -= sec * NSEC_PER_SEC
elif ts.tv_nsec < 0:
     # div_round_up(abs(ts->tv_nsec), NSEC_PER_SEC)
         sec = (NSEC_PER_SEC - ts.tv_nsec - 1) / NSEC_PER_SEC
         ts.tv_sec -= sec;
         ts.tv_nsec += sec * NSEC_PER_SEC;

Note

There are two cases where the normalization can result in integer overflow. These can be extrapolated to not simply overflowing the tv_sec field by one second, but also by any realizable multiple of NSEC_PER_SEC.

1. When tv_nsec is negative and tv_sec is already most negative.
2. When tv_nsec is greater-or-equal to NSEC_PER_SEC and tv_sec is already most positive.

If the operation would result in integer overflow, return value is false.

Note

ts must be non-NULL.

Parameters

ts	the timespec to be normalized

Returns

true if the operation completes successfully, otherwise false.

timespec_sub()

static bool timespec_sub ( struct timespec *  a, const struct timespec *  b  )

inlinestatic

#include <include/zephyr/sys/timeutil.h>

Subtract one timespec from another.

This function subtracts the timespec pointed to by b from the timespec pointed to by a and stores the result in the timespce pointed to by a.

If the operation would result in integer overflow, return value is false.

Note

a and b must be non-NULL.

Parameters

a	the timespec which is subtracted from
b	the timespec to be subtracted

Returns

true if the operation is successful, otherwise false.