solemnwarning / timespec

Functions for working with timespec structures

Introduction

This library provides functions for working with timespec structures.

It aims to provide a comprehensive set of functions with well-defined behaviour that handle all edge cases (e.g. negative values) in a sensible manner.

Negative values are allowed in the tv_sec and/or tv_usec field of timespec structures, tv_usec is always relative to tv_sec, so mixing positive and negative values will produce consistent results:

{ tv_sec = 1,  tv_nsec = 500000000  } ==  1.5 seconds
{ tv_sec = 1,  tv_nsec = 0          } ==  1.0 seconds
{ tv_sec = 1,  tv_nsec = -500000000 } ==  0.5 seconds
{ tv_sec = 0,  tv_nsec = 500000000  } ==  0.5 seconds
{ tv_sec = 0,  tv_nsec = 0          } ==  0.0 seconds
{ tv_sec = 0,  tv_nsec = -500000000 } == -0.5 seconds
{ tv_sec = -1, tv_nsec = 500000000  } == -0.5 seconds
{ tv_sec = -1, tv_nsec = 0          } == -1.0 seconds
{ tv_sec = -1, tv_nsec = -500000000 } == -1.5 seconds

Furthermore, any timespec structures processed or returned by library functions are normalised according to the rules defined by timespec_normalise().

A test program for your platform can be produced by compiling with -DTEST.

This is public domain. Feel free to embed it in your software if it meets your needs.

Functions

Maths functions

struct timespec timespec_add(struct timespec ts1, struct timespec ts2)

Returns the result of adding two timespec structures.

struct timespec timespec_sub(struct timespec ts1, struct timespec ts2)

Returns the result of subtracting ts2 from ts1.

struct timespec timespec_mod(struct timespec ts1, struct timespec ts2)

Returns the remainder left over after dividing ts1 by ts2.

Clamping

struct timespec timespec_min(struct timespec ts1, struct timespec ts2);

Return the lesser one of the two given timespec values.

struct timespec timespec_max(struct timespec ts1, struct timespec ts2);

Return the greater one of the two given timespec values.

struct timespec timespec_clamp(struct timespec ts1, struct timespec min, struct timespec max);

Clamp the value of TS between MIN and MAX.

Comparison functions

int timespec_cmp(struct timespec ts1, struct timespec ts2)

Returns (1, 0, -1) if ts1 is (greater than, equal to, less than) ts2.

bool timespec_eq(struct timespec ts1, struct timespec ts2)

Returns true if the two timespec structures are equal.

bool timespec_gt(struct timespec ts1, struct timespec ts2)

Returns true if ts1 is greater than ts2.

bool timespec_ge(struct timespec ts1, struct timespec ts2)

Returns true if ts1 is greater than or equal to ts2.

bool timespec_lt(struct timespec ts1, struct timespec ts2)

Returns true if ts1 is less than ts2.

bool timespec_le(struct timespec ts1, struct timespec ts2)

Returns true if ts1 is less than or equal to ts2.

Conversion funtions

struct timespec timespec_from_double(double s)

Converts a fractional number of seconds to a timespec.

double timespec_to_double(struct timespec ts)

Converts a timespec to a fractional number of seconds.

struct timespec timespec_from_timeval(struct timeval tv)

Converts a timeval to a timespec.

struct timeval timespec_to_timeval(struct timespec ts)

Converts a timespec to a timeval.

struct timespec timespec_from_ms(long milliseconds)

Converts an integer number of milliseconds to a timespec.

long timespec_to_ms(struct timespec ts)

Converts a timespec to an integer number of milliseconds.

Normalisation

struct timespec timespec_normalise(struct timespec ts)

Returns a normalised version of a timespec structure, according to the following rules:

1. If tv_nsec is >=1,000,000,00 or <=-1,000,000,000, flatten the surplus nanoseconds into the tv_sec field.

2. If tv_nsec is negative, decrement tv_sec and roll tv_nsec up to represent the same value attainable by ADDING nanoseconds to tv_sec.

timespec's Issues

Tests won't pass on 32-bit platforms

Hi! Firstly, thanks for your library. It's quite a bit easier to deal with the timespec struct with your functions.

When our team started using your library, we noticed your tests do not pass on our 32-bit ARM platform. Fixing them was simple once we figured out what was going on: a few of your test cases are using numbers that overflow tv_nsec. We've refactored your project structure quite a bit, so a pull request doesn't make a lot of sense, but here's the patch fix

From d45114a1848221797c6275c7e3ac464c317bcc5e Mon Sep 17 00:00:00 2001
From: David Zemon <[email protected]>
Date: Thu, 25 Jul 2019 09:29:27 -0500
Subject: [PATCH] Don't run invalid tests on 32-bit platforms

---
 test/timespecTests.c | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/test/timespecTests.c b/test/timespecTests.c
index d33ad51..3923930 100644
--- a/test/timespecTests.c
+++ b/test/timespecTests.c
@@ -326,6 +326,9 @@ int main()
     TEST_NORMALISE(-5,-1000000000, -6,0);
     TEST_NORMALISE(-5,-1500000000, -6,-500000000);
 
+#if (64 <= __WORDSIZE)
+    /* These tests use more than 32-bits for the nanosecond field and are
+       therefore not expected to succeed on 32-bit platforms */
     TEST_NORMALISE(0,2000000000,  2,0);
     TEST_NORMALISE(0,2500000000,  2,500000000);
     TEST_NORMALISE(0,-2000000000, -2,0);
@@ -337,6 +340,7 @@ int main()
 
     TEST_NORMALISE(-1,500000000,  0,-500000000);
     TEST_NORMALISE(-1,499999999,  0,-500000001);
+#endif
 
     if(result > 0)
     {
@@ -347,4 +351,4 @@ int main()
     }
 
     return result;
-}
\ No newline at end of file
+}
-- 
2.10.5

Long story short: just gotta wrap the last few TEST_NORMALISE test cases with #if (64 <= __WORDSIZE)

Possible Y2038 problem in `timespec_from_double`.

timespec_from_double has this initialized variable:

	struct timespec ts = {
		.tv_sec  = s,
		.tv_nsec = (s - (long)(s)) * NSEC_PER_SEC,
	};

On platforms with 32-bit long and the usual Unix time epoch of Jan 1, 1970, this will suffer from the Year 2038 problem even if the platform uses a 64-bit time_t.

The C standard declares the tv_sec member to be of type time_t, so it should be sufficient to replace the conversion (long)(s) with (time_t)(s) (assuming time_t is an integer type because the existing code already assumes that!).

timespec_normalise incorrect according to posix

Hi, I found this repo while looking something up. I found a small bug: https://pubs.opengroup.org/onlinepubs/007908799/xsh/realtime.html says "The tv_nsec member is only valid if greater than or equal to zero, and less than the number of nanoseconds in a second (1000 million)". So {0, -500000000} should be normalized to {-1, 500000000}.

My personal branch of this library

Hello!

I would just like to inform you that I have inadvertently forked your library.

My version has by now diverged significantly, but maybe you can find something useful in the commit history. You can find my working branch here https://github.com/promovicz/timespec.

Some of my recent commits have fixed rounding bugs, some of which are related to issue #4. My version of the library also has a compatibility layer for an old Solaris utility header. Some of it even has tests. In fact the test vectors/values might be worth reviewing and adjusting with regards to #4.

Best Regards
prom