timespec.c File Reference

Functions for working with timespec structures. More...

#include <limits.h>
#include <stdbool.h>
#include <sys/time.h>
#include <time.h>
#include "timespec.h"

Include dependency graph for timespec.c:

Macros
#define	NSEC_PER_SEC   1000000000

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 (ts1ts2).
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 ts, struct timespec min, struct timespec max)
	Clamp the value of TS between MIN and MAX.
int	timespec_cmp (struct timespec ts1, struct timespec ts2)
	Returns (1, 0, -1) if ts1 is (greater than, equal to, less than) to 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.
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.
struct timespec	timespec_normalise (struct timespec ts)
	Normalises a timespec structure.

Detailed Description

Functions for working with timespec structures.

This library 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 structure processed or returned by library functions is normalised according to the rules in timespec_normalise().

Function Documentation

timespec_normalise()

struct timespec timespec_normalise

(

struct timespec

ts

)

Normalises a timespec structure.

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.