Zephyr Project API 4.1.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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
athe timespec which is added to
bthe 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
athe first timespec to compare
bthe 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
athe first timespec to compare
bthe 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
tsthe 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
tsThe 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
tsthe 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
athe timespec which is subtracted from
bthe timespec to be subtracted
Returns
true if the operation is successful, otherwise false.