epicsTime.h

EPICS time-stamps (epicsTimeStamp), epicsTime C++ class and C functions for handling wall-clock times.

Author

Jeffrey O. Hill

Return status values

epicsTime routines return S_time_ error status values:

epicsTimeOK

Success.

S_time_noProvider

No time provider.

S_time_badEvent

Bad event number.

S_time_badArgs

Invalid arguments.

S_time_noMemory

Out of memory.

S_time_unsynchronized

Provider not synchronized.

S_time_timezone

Invalid timezone.

S_time_conversion

Time conversion error.

epicsTimeEvent numbers

Some special values for eventNumber:

epicsTimeEventCurrentTime
epicsTimeEventBestTime
epicsTimeEventDeviceTime

generalTime functions

These are implemented in the “generalTime” framework:

int epicsTimeGetCurrent(epicsTimeStamp *pDest)

Get current time into *pDest.

int epicsTimeGetEvent(epicsTimeStamp *pDest, int eventNumber)

Get time of event eventNumber into *pDest.

int epicsTimeGetMonotonic(epicsTimeStamp *pDest)

Get monotonic time into *pDest.

ISR-callable

These routines may be called from an Interrupt Service Routine, and will return a value from the last current time or event time provider that sucessfully returned a result from the equivalent non-ISR routine.

int epicsTimeGetCurrentInt(epicsTimeStamp *pDest)

Get current time into *pDest (ISR-safe)

int epicsTimeGetEventInt(epicsTimeStamp *pDest, int eventNumber)

Get time of event eventNumber into *pDest (ISR-safe)

ANSI C time_t conversions

Convert to and from ANSI C time_t

int epicsTimeToTime_t(time_t *pDest, const epicsTimeStamp *pSrc)

Convert epicsTimeStamp to ANSI C time_t.

int epicsTimeFromTime_t(epicsTimeStamp *pDest, time_t src)

Convert ANSI C time_t to epicsTimeStamp.

ANSI C struct tm conversions

Convert to and from ANSI C’s struct tm with nanoseconds

int epicsTimeToTM(struct tm *pDest, unsigned long *pNSecDest, const epicsTimeStamp *pSrc)

Convert epicsTimeStamp to struct tm in local time zone.

int epicsTimeToGMTM(struct tm *pDest, unsigned long *pNSecDest, const epicsTimeStamp *pSrc)

Convert epicsTimeStamp to struct tm in UTC/GMT.

int epicsTimeFromTM(epicsTimeStamp *pDest, const struct tm *pSrc, unsigned long nSecSrc)

Set epicsTimeStamp from struct tm in local time zone.

int epicsTimeFromGMTM(epicsTimeStamp *pDest, const struct tm *pSrc, unsigned long nSecSrc)

Set epicsTimeStamp from struct tm in UTC/GMT.

POSIX RT struct timespec conversions

Convert to and from the POSIX RealTime struct timespec format.

int epicsTimeToTimespec(struct timespec *pDest, const epicsTimeStamp *pSrc)

Convert epicsTimeStamp to struct timespec

int epicsTimeFromTimespec(epicsTimeStamp *pDest, const struct timespec *pSrc)

Set epicsTimeStamp from struct timespec

BSD’s struct timeval conversions

Convert to and from the BSD struct timeval format.

int epicsTimeToTimeval(struct timeval *pDest, const epicsTimeStamp *pSrc)

Convert epicsTimeStamp to struct timeval

int epicsTimeFromTimeval(epicsTimeStamp *pDest, const struct timeval *pSrc)

Set epicsTimeStamp from struct timeval

Arithmetic operations

Arithmetic operations on epicsTimeStamp objects and time differences which are normally expressed as a double in seconds.

double epicsTimeDiffInSeconds(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)

Time difference between left and right in seconds.

void epicsTimeAddSeconds(epicsTimeStamp *pDest, double secondsToAdd)

Add some number of seconds to dest.

epicsInt64 epicsTimeDiffInNS(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)

Time difference between left and right, as a signed integer number of nanoseconds.

Since

EPICS 7.0.6.1

Comparison operators

Comparisons between epicsTimeStamp objects, returning 0=false, 1=true.

int epicsTimeEqual(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)

left equals right

int epicsTimeNotEqual(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)

left not equal to right

int epicsTimeLessThan(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)

left was before right

int epicsTimeLessThanEqual(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)

right was no later than left

int epicsTimeGreaterThan(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)

left was after right

int epicsTimeGreaterThanEqual(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)

right was not before left

Re-entrant time_t to struct tm conversions

OS-specific reentrant versions of the ANSI C interface because the vxWorks gmtime_r interface does not match POSIX standards

int epicsTime_localtime(const time_t *clock, struct tm *result)

Break down a time_t into a struct tm in the local timezone.

int epicsTime_gmtime(const time_t *clock, struct tm *result)

Break down a time_t into a struct tm in the UTC timezone.

Monotonic time routines

epicsUInt64 epicsMonotonicResolution(void)

Monotonic time resolution, may not be accurate. Returns the minimum non-zero time difference between two calls to epicsMonotonicGet() in units of nanoseconds.

epicsUInt64 epicsMonotonicGet(void)

Fetch monotonic counter, returns the number of nanoseconds since some unspecified time.

Defines

POSIX_TIME_AT_EPICS_EPOCH

The EPICS Epoch is 00:00:00 Jan 1, 1990 UTC.

TS_STAMP

Old time-stamp data type, deprecated.

Deprecated:

TS_STAMP was provided for compatibility with Base-3.13 code. It will be removed in some future release of EPICS 7.

Typedefs

typedef epicsUInt64 epicsUTag

Type of UTAG field (dbCommon::utag)

Functions

size_t epicsTimeToStrftime(char *pBuff, size_t bufLength, const char *pFormat, const epicsTimeStamp *pTS)

Convert epicsTimeStamp to string. See epicsTime::strftime()

void epicsTimeShow(const epicsTimeStamp*, unsigned interestLevel)

Dump current state to stdout.

std::ostream &operator<<(std::ostream &strm, const epicsTime &ts)
struct epicsTimeStamp
#include <epicsTime.h>

EPICS time stamp, for use from C code.

Because it uses an unsigned 32-bit integer to hold the seconds count, an epicsTimeStamp can safely represent time stamps until the year 2106.

Public Members

epicsUInt32 secPastEpoch

seconds since 0000 Jan 1, 1990

epicsUInt32 nsec

nanoseconds within second

struct local_tm_nano_sec
#include <epicsTime.h>

C++ only ANSI C struct tm with nanoseconds, local timezone.

Extend ANSI C “struct tm” to include nano seconds within a second and a struct tm that is adjusted for the local timezone.

Public Members

struct tm ansi_tm

ANSI C time details.

unsigned long nSec

nanoseconds extension

struct gm_tm_nano_sec
#include <epicsTime.h>

C++ only ANSI C sruct tm with nanoseconds, UTC.

Extend ANSI C “struct tm” to include nanoseconds within a second and a struct tm that is adjusted for GMT (UTC).

Public Members

struct tm ansi_tm

ANSI C time details.

unsigned long nSec

nanoseconds extension

struct time_t_wrapper
#include <epicsTime.h>

C++ only ANSI C time_t.

This is for converting to/from the ANSI C time_t. Since time_t is usually an elementary type providing a conversion operator from time_t to/from epicsTime could cause undesirable implicit conversions. Providing a conversion operator to/from the time_t_wrapper instead prevents implicit conversions.

Public Members

time_t ts
class epicsTimeEvent
#include <epicsTime.h>

C++ Event number wrapper class.

Stores an event number for use by the epicsTime::getEvent() static class method.

Public Functions

inline epicsTimeEvent(const int &number)
inline operator int() const

Private Members

int eventNumber
class epicsTime
#include <epicsTime.h>

C++ time stamp object.

Holds an EPICS time stamp, and provides conversion functions for both input and output from/to other types.

Note

Time conversions: The epicsTime implementation will properly convert between the various formats from the beginning of the EPICS epoch until at least 2038. Unless the underlying architecture support has defective POSIX, BSD/SRV5, or standard C time support the EPICS implementation should be valid until 2106.

epicsTimeStamp conversions

Convert to and from EPICS epicsTimeStamp format

inline operator const epicsTimeStamp&() const

Convert to epicsTimeStamp.

epicsTime(const epicsTimeStamp &replace)

Construct from epicsTimeStamp.

inline epicsTime &operator=(const epicsTimeStamp &replace)

Assign from epicsTimeStamp.

ANSI C time_t conversions

Convert to and from ANSI C time_t wrapper .

inline operator time_t_wrapper() const

Convert to ANSI C time_t.

inline epicsTime(const time_t_wrapper &replace)

Construct from ANSI C time_t.

inline epicsTime &operator=(const time_t_wrapper &replace)

Assign from ANSI C time_t.

ANSI C struct tm local-time conversions

Convert to and from ANSI Cs struct tm (with nano seconds), adjusted for the local time zone.

inline operator local_tm_nano_sec() const

Convert to struct tm in local time zone.

inline epicsTime(const local_tm_nano_sec &replace)

Construct from struct tm in local time zone.

inline epicsTime &operator=(const local_tm_nano_sec &replace)

Assign from struct tm in local time zone.

ANSI C struct tm UTC conversions

Convert to and from ANSI Cs struct tm (with nano seconds), adjusted for Greenwich Mean Time (UTC).

inline operator gm_tm_nano_sec() const

Convert to struct tm in UTC/GMT.

inline epicsTime(const gm_tm_nano_sec &replace)

Construct from struct tm in UTC/GMT.

inline epicsTime &operator=(const gm_tm_nano_sec &replace)

Assign from struct tm in UTC.

POSIX RT struct timespec conversions

Convert to and from the POSIX RealTime struct timespec format.

inline operator struct timespec() const

Convert to struct timespec

inline epicsTime(const struct timespec &replace)

Construct from struct timespec

inline epicsTime &operator=(const struct timespec &replace)

Assign from struct timespec

BSD’s struct timeval conversions

Convert to and from the BSD struct timeval format.

operator struct timeval() const

Convert to struct timeval

epicsTime(const struct timeval &replace)

Construct from struct timeval

epicsTime &operator=(const struct timeval &replace)

Assign from struct timeval

Arithmetic operators

Standard operators involving epicsTime objects and time differences which are always expressed as a double in seconds.

inline double operator-(const epicsTime &other) const

lhs minus rhs, in seconds

inline epicsTime operator+(double delta) const

lhs plus rhs seconds

inline epicsTime operator-(double delta) const

lhs minus rhs seconds

inline epicsTime operator+=(double delta)

add rhs seconds to lhs

inline epicsTime operator-=(double delta)

subtract rhs seconds from lhs

Comparison operators

Standard comparisons between epicsTime objects.

inline bool operator==(const epicsTime &other) const

lhs equals rhs

inline bool operator!=(const epicsTime &other) const

lhs not equal to rhs

inline bool operator<=(const epicsTime &other) const

rhs no later than lhs

inline bool operator<(const epicsTime &other) const

lhs was before rhs

inline bool operator>=(const epicsTime &other) const

rhs not before lhs

inline bool operator>(const epicsTime &other) const

lhs was after rhs

Public Types

typedef std::runtime_error unableToFetchCurrentTime

Exception: Time provider problem.

typedef std::logic_error formatProblemWithStructTM

Exception: Bad field(s) in struct tm

Public Functions

inline epicsTime()

The default constructor sets the time to the EPICS epoch.

inline size_t strftime(char *pBuff, size_t bufLength, const char *pFormat) const

Convert to string in user-specified format.

This method extends the standard C library routine strftime(). See your OS documentation for details about the standard routine. The epicsTime method adds support for printing the fractional portion of the time. It searches the format string for the sequence %0f where n is the desired precision, and uses this format to convert the fractional seconds with the requested precision. For example:

epicsTime time = epicsTime::getCurrent();
char buf[30];
time.strftime(buf, 30, "%Y-%m-%d %H:%M:%S.%06f");
printf("%s\n", buf);
This will print the current time in the format:
2001-01-26 20:50:29.813505

inline void show(unsigned interestLevel) const

Dump current state to standard out.

Public Static Functions

static inline epicsTime getEvent(const epicsTimeEvent &evt)

Get time of event system event.

Returns an epicsTime indicating when the associated event system event last occurred.

static epicsTime getCurrent()

Get current clock time.

Returns an epicsTime containing the current time. For example:

epicsTime now = epicsTime::getCurrent();

static inline epicsTime getMonotonic()

Get current monotonic time.

Returns an epicsTime containing the current monotonic time, an OS clock which never going backwards or jumping forwards. This time is has an undefined epoch, and is only useful for measuring time differences.

Private Members

epicsTimeStamp ts

Private Static Functions

static void throwError(int code)