epicsTime.h File Reference

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

#include <time.h>
#include "libComAPI.h"
#include "epicsTypes.h"
#include "osdTime.h"
#include "errMdef.h"

Include dependency graph for epicsTime.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	epicsTimeStamp
	EPICS time stamp, for use from C code. More...

Macros
#define	POSIX_TIME_AT_EPICS_EPOCH   631152000u
	The EPICS Epoch is 00:00:00 Jan 1, 1990 UTC. More...
#define	TS_STAMP   epicsTimeStamp
	Old time-stamp data type, deprecated. More...
Return status values
epicsTime routines return S_time_ error status values:
#define	epicsTimeOK   0
	Success. More...
#define	S_time_noProvider   (M_time| 1) /*No time provider*/
	No time provider. More...
#define	S_time_badEvent   (M_time| 2) /*Bad event number*/
	Bad event number. More...
#define	S_time_badArgs   (M_time| 3) /*Invalid arguments*/
	Invalid arguments. More...
#define	S_time_noMemory   (M_time| 4) /*Out of memory*/
	Out of memory. More...
#define	S_time_unsynchronized   (M_time| 5) /*Provider not synchronized*/
	Provider not synchronized. More...
#define	S_time_timezone   (M_time| 6) /*Invalid timezone*/
	Invalid timezone. More...
#define	S_time_conversion   (M_time| 7) /*Time conversion error*/
	Time conversion error. More...
epicsTimeEvent numbers
Some special values for eventNumber:
#define	epicsTimeEventCurrentTime   0
#define	epicsTimeEventBestTime   -1
#define	epicsTimeEventDeviceTime   -2

Typedefs
typedef struct epicsTimeStamp	epicsTimeStamp
	EPICS time stamp, for use from C code. More...

Functions
LIBCOM_API size_t epicsStdCall	epicsTimeToStrftime (char *pBuff, size_t bufLength, const char *pFormat, const epicsTimeStamp *pTS)
	Convert epicsTimeStamp to string. See epicsTime::strftime() More...
LIBCOM_API void epicsStdCall	epicsTimeShow (const epicsTimeStamp *, unsigned interestLevel)
	Dump current state to stdout. More...
generalTime functions
These are implemented in the "generalTime" framework:
LIBCOM_API int epicsStdCall	epicsTimeGetCurrent (epicsTimeStamp *pDest)
	Get current time into *pDest. More...
LIBCOM_API int epicsStdCall	epicsTimeGetEvent (epicsTimeStamp *pDest, int eventNumber)
	Get time of event eventNumber into *pDest. More...
LIBCOM_API int	epicsTimeGetMonotonic (epicsTimeStamp *pDest)
	Get monotonic time into *pDest. More...
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.
LIBCOM_API int	epicsTimeGetCurrentInt (epicsTimeStamp *pDest)
	Get current time into *pDest (ISR-safe) More...
LIBCOM_API int	epicsTimeGetEventInt (epicsTimeStamp *pDest, int eventNumber)
	Get time of event eventNumber into *pDest (ISR-safe) More...
ANSI C time_t conversions
Convert to and from ANSI C time_t
LIBCOM_API int epicsStdCall	epicsTimeToTime_t (time_t *pDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to ANSI C time_t. More...
LIBCOM_API int epicsStdCall	epicsTimeFromTime_t (epicsTimeStamp *pDest, time_t src)
	Convert ANSI C time_t to epicsTimeStamp. More...
ANSI C struct tm conversions
Convert to and from ANSI C's struct tm with nanoseconds
LIBCOM_API int epicsStdCall	epicsTimeToTM (struct tm *pDest, unsigned long *pNSecDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to struct tm in local time zone. More...
LIBCOM_API int epicsStdCall	epicsTimeToGMTM (struct tm *pDest, unsigned long *pNSecDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to struct tm in UTC/GMT. More...
LIBCOM_API int epicsStdCall	epicsTimeFromTM (epicsTimeStamp *pDest, const struct tm *pSrc, unsigned long nSecSrc)
	Set epicsTimeStamp from struct tm in local time zone. More...
LIBCOM_API int epicsStdCall	epicsTimeFromGMTM (epicsTimeStamp *pDest, const struct tm *pSrc, unsigned long nSecSrc)
	Set epicsTimeStamp from struct tm in UTC/GMT. More...
POSIX RT struct timespec conversions
Convert to and from the POSIX RealTime struct timespec format.
LIBCOM_API int epicsStdCall	epicsTimeToTimespec (struct timespec *pDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to struct timespec More...
LIBCOM_API int epicsStdCall	epicsTimeFromTimespec (epicsTimeStamp *pDest, const struct timespec *pSrc)
	Set epicsTimeStamp from struct timespec More...
BSD's struct timeval conversions
Convert to and from the BSD struct timeval format.
LIBCOM_API int epicsStdCall	epicsTimeToTimeval (struct timeval *pDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to struct timeval More...
LIBCOM_API int epicsStdCall	epicsTimeFromTimeval (epicsTimeStamp *pDest, const struct timeval *pSrc)
	Set epicsTimeStamp from struct timeval More...
Arithmetic operations
Arithmetic operations on epicsTimeStamp objects and time differences which are always expressed as a double in seconds.
LIBCOM_API double epicsStdCall	epicsTimeDiffInSeconds (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	Time difference between left and right in seconds. More...
LIBCOM_API void epicsStdCall	epicsTimeAddSeconds (epicsTimeStamp *pDest, double secondsToAdd)
	Add some number of seconds to dest. More...
Comparison operators
Comparisons between epicsTimeStamp objects, returning 0=false, 1=true.
LIBCOM_API int epicsStdCall	epicsTimeEqual (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	left equals right More...
LIBCOM_API int epicsStdCall	epicsTimeNotEqual (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	left not equal to right More...
LIBCOM_API int epicsStdCall	epicsTimeLessThan (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	left was before right More...
LIBCOM_API int epicsStdCall	epicsTimeLessThanEqual (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	right was no later than left More...
LIBCOM_API int epicsStdCall	epicsTimeGreaterThan (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	left was after right More...
LIBCOM_API int epicsStdCall	epicsTimeGreaterThanEqual (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	right was not before left More...
Reentrant 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
LIBCOM_API int epicsStdCall	epicsTime_localtime (const time_t *clock, struct tm *result)
	Break down a time_t into a struct tm in the local timezone. More...
LIBCOM_API int epicsStdCall	epicsTime_gmtime (const time_t *clock, struct tm *result)
	Break down a time_t into a struct tm in the UTC timezone. More...
Monotonic time routines
LIBCOM_API 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. More...
LIBCOM_API epicsUInt64	epicsMonotonicGet (void)
	Fetch monotonic counter, returns the number of nanoseconds since some unspecified time. More...

Detailed Description

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

Author

Jeffrey O. Hill

Definition in file epicsTime.h.

Macro Definition Documentation

#define epicsTimeEventBestTime   -1

Definition at line 361 of file epicsTime.h.

#define epicsTimeEventCurrentTime   0

Definition at line 360 of file epicsTime.h.

#define epicsTimeEventDeviceTime   -2

Definition at line 362 of file epicsTime.h.

#define epicsTimeOK   0

Success.

Definition at line 339 of file epicsTime.h.

#define POSIX_TIME_AT_EPICS_EPOCH   631152000u

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

Definition at line 26 of file epicsTime.h.

#define S_time_badArgs   (M_time| 3) /*Invalid arguments*/

Invalid arguments.

Definition at line 345 of file epicsTime.h.

#define S_time_badEvent   (M_time| 2) /*Bad event number*/

Bad event number.

Definition at line 343 of file epicsTime.h.

#define S_time_conversion   (M_time| 7) /*Time conversion error*/

Time conversion error.

Definition at line 353 of file epicsTime.h.

#define S_time_noMemory   (M_time| 4) /*Out of memory*/

Out of memory.

Definition at line 347 of file epicsTime.h.

#define S_time_noProvider   (M_time| 1) /*No time provider*/

No time provider.

Definition at line 341 of file epicsTime.h.

#define S_time_timezone   (M_time| 6) /*Invalid timezone*/

Invalid timezone.

Definition at line 351 of file epicsTime.h.

#define S_time_unsynchronized   (M_time| 5) /*Provider not synchronized*/

Provider not synchronized.

Definition at line 349 of file epicsTime.h.

#define TS_STAMP   epicsTimeStamp

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.

Definition at line 42 of file epicsTime.h.

Typedef Documentation

typedef struct epicsTimeStamp epicsTimeStamp

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.

Function Documentation

LIBCOM_API epicsUInt64 epicsMonotonicGet

(

void

)

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

Definition at line 29 of file osdMonotonic.c.

{
    uint64_t val = mach_absolute_time();
    return val * tbinfo.numer / tbinfo.denom;
}

LIBCOM_API 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.

Definition at line 24 of file osdMonotonic.c.

{
    return 1e-9 * tbinfo.numer / tbinfo.denom;
}

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

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

Definition at line 55 of file osdTime.cpp.

{
    return gmtime_r(pAnsiTime, pTM) ?
        epicsTimeOK : errno;
}

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

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

Definition at line 61 of file osdTime.cpp.

{
    return localtime_r(clock, result) ?
        epicsTimeOK : errno;
}

LIBCOM_API void epicsStdCall epicsTimeAddSeconds	(	epicsTimeStamp *	pDest,
		double	secondsToAdd
	)

Add some number of seconds to dest.

Definition at line 1057 of file epicsTime.cpp.

    {
        try {
            *pDest = epicsTime (*pDest) + seconds;
        }
        catch ( ... ) {
            *pDest = epicsTime ();
        }
    }

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

Time difference between left and right in seconds.

Definition at line 1048 of file epicsTime.cpp.

    {
        try {
            return epicsTime (*pLeft) - epicsTime (*pRight);
        }
        catch (...) {
            return - DBL_MAX;
        }
    }

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

left equals right

Definition at line 1066 of file epicsTime.cpp.

    {
        try {
            return epicsTime (*pLeft) == epicsTime (*pRight);
        }
        catch ( ... ) {
            return 0;
        }
    }

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

Set epicsTimeStamp from struct tm in UTC/GMT.

Definition at line 995 of file epicsTime.cpp.

    {
        try {
            gm_tm_nano_sec tmns;
            tmns.ansi_tm = *pSrc;
            tmns.nSec = nSecSrc;
            *pDest = epicsTime (tmns);
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

LIBCOM_API int epicsStdCall epicsTimeFromTime_t	(	epicsTimeStamp *	pDest,
		time_t	src
	)

Convert ANSI C time_t to epicsTimeStamp.

Definition at line 944 of file epicsTime.cpp.

    {
        try {
            time_t_wrapper dst;
            dst.ts = src;
            *pDest = epicsTime ( dst );
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

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

Set epicsTimeStamp from struct timespec

Definition at line 1018 of file epicsTime.cpp.

    {
        try {
            *pDest = epicsTime (*pSrc);
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

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

Set epicsTimeStamp from struct timeval

Definition at line 1038 of file epicsTime.cpp.

    {
        try {
            *pDest = epicsTime (*pSrc);
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

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

Set epicsTimeStamp from struct tm in local time zone.

Definition at line 982 of file epicsTime.cpp.

    {
        try {
            local_tm_nano_sec tmns;
            tmns.ansi_tm = *pSrc;
            tmns.nSec = nSecSrc;
            *pDest = epicsTime (tmns);
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

LIBCOM_API int epicsStdCall epicsTimeGetCurrent

(

epicsTimeStamp *

pDest

)

Get current time into *pDest.

Definition at line 152 of file epicsGeneralTime.c.

{
    gtProvider *ptp;
    int status = S_time_noProvider;
    epicsTimeStamp ts;

    if(useOsdGetCurrent)
        return osdTimeGetCurrent(pDest);

    generalTime_Init();

    IFDEBUG(20)
        printf("epicsTimeGetCurrent()\n");

    epicsMutexMustLock(gtPvt.timeListLock);
    for (ptp = (gtProvider *)ellFirst(&gtPvt.timeProviders);
         ptp; ptp = (gtProvider *)ellNext(&ptp->node)) {

        status = ptp->get.Time(&ts);
        if (status == epicsTimeOK) {
            /* check time is monotonic */
            if (epicsTimeGreaterThanEqual(&ts, &gtPvt.lastProvidedTime)) {
                *pDest = ts;
                gtPvt.lastProvidedTime = ts;
                gtPvt.lastTimeProvider = ptp;
            } else {
                int key;

                *pDest = gtPvt.lastProvidedTime;
                key = epicsInterruptLock();
                gtPvt.ErrorCounts++;
                epicsInterruptUnlock(key);

                IFDEBUG(10) {
                    char last[40], buff[40];

                    epicsTimeToStrftime(last, sizeof(last), tsfmt,
                        &gtPvt.lastProvidedTime);
                    epicsTimeToStrftime(buff, sizeof(buff), tsfmt, &ts);
                    printf("eTGC provider '%s' returned older time\n"
                        "    %s, using %s instead\n", ptp->name, buff, last);
                }
            }
            break;
        }
    }
    if (status)
        gtPvt.lastTimeProvider = NULL;
    epicsMutexUnlock(gtPvt.timeListLock);

    IFDEBUG(20) {
        if (ptp && status == epicsTimeOK) {
            char buff[40];

            epicsTimeToStrftime(buff, sizeof(buff), tsfmt, &ts);
            printf("eTGC returning %s from provider '%s'\n",
                buff, ptp->name);
        }
        else
            printf("eTGC returning error\n");
    }

    return status;
}

LIBCOM_API int epicsTimeGetCurrentInt

(

epicsTimeStamp *

pDest

)

Get current time into *pDest (ISR-safe)

Definition at line 225 of file epicsGeneralTime.c.

{
    gtProvider *ptp = gtPvt.lastTimeProvider;

    if (ptp == NULL ||
        ptp->getInt.Time == NULL) {
        IFDEBUG(20)
            epicsInterruptContextMessage("eTGCInt: No support\n");
        return S_time_noProvider;
    }

    return ptp->getInt.Time(pDest);
}

LIBCOM_API int epicsStdCall epicsTimeGetEvent	(	epicsTimeStamp *	pDest,
		int	eventNumber
	)

Get time of event eventNumber into *pDest.

Definition at line 341 of file epicsGeneralTime.c.

{
    if (eventNumber == epicsTimeEventCurrentTime) {
        return epicsTimeGetCurrent(pDest);
    } else {
        return generalTimeGetEventPriority(pDest, eventNumber, NULL);
    }
}

LIBCOM_API int epicsTimeGetEventInt	(	epicsTimeStamp *	pDest,
		int	eventNumber
	)

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

Definition at line 350 of file epicsGeneralTime.c.

{
    if (eventNumber == epicsTimeEventCurrentTime) {
        return epicsTimeGetCurrentInt(pDest);
    } else {
        gtProvider *ptp = gtPvt.lastEventProvider;

        if (ptp == NULL ||
            ptp->getInt.Event == NULL) {
            IFDEBUG(20)
                epicsInterruptContextMessage("eTGEvInt: No support\n");
            return S_time_noProvider;
        }

        return ptp->getInt.Event(pDest, eventNumber);
    }
}

LIBCOM_API int epicsTimeGetMonotonic

(

epicsTimeStamp *

pDest

)

Get monotonic time into *pDest.

Definition at line 217 of file epicsGeneralTime.c.

{
    epicsUInt64 now = epicsMonotonicGet();
    pDest->nsec = now%1000000000ul;
    pDest->secPastEpoch = now/1000000000ul;
    return 0;
}

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

left was after right

Definition at line 1102 of file epicsTime.cpp.

    {
        try {
            return epicsTime (*pLeft) > epicsTime (*pRight);
        }
        catch ( ... ) {
            return 0;
        }
    }

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

right was not before left

Definition at line 1111 of file epicsTime.cpp.

    {
        try {
            return epicsTime (*pLeft) >= epicsTime (*pRight);
        }
        catch ( ... ) {
            return 0;
        }
    }

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

left was before right

Definition at line 1084 of file epicsTime.cpp.

    {
        try {
            return epicsTime (*pLeft) < epicsTime (*pRight);
        }
        catch ( ... ) {
            return 0;
        }
    }

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

right was no later than left

Definition at line 1093 of file epicsTime.cpp.

    {
        try {
            return epicsTime (*pLeft) <= epicsTime (*pRight);
        }
        catch ( ... ) {
            return 0;
        }
    }

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

left not equal to right

Definition at line 1075 of file epicsTime.cpp.

    {
        try {
            return epicsTime (*pLeft) != epicsTime (*pRight);
        }
        catch ( ... ) {
            return 1;
        }
    }

LIBCOM_API void epicsStdCall epicsTimeShow	(	const epicsTimeStamp *	,
		unsigned	interestLevel
	)

Dump current state to stdout.

Definition at line 1129 of file epicsTime.cpp.

    {
        try {
            epicsTime(*pTS).show (interestLevel);
        }
        catch ( ... ) {
            printf ( "Invalid epicsTimeStamp\n" );
        }
    }

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

Convert epicsTimeStamp to struct tm in UTC/GMT.

Definition at line 969 of file epicsTime.cpp.

    {
        try {
            gm_tm_nano_sec gmtmns = epicsTime (*pSrc);
            *pDest = gmtmns.ansi_tm;
            if (pNSecDest)
                *pNSecDest = gmtmns.nSec;
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

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

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

Definition at line 1120 of file epicsTime.cpp.

    {
        try {
            return epicsTime(*pTS).strftime (pBuff, bufLength, pFormat);
        }
        catch ( ... ) {
            return 0;
        }
    }

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

Convert epicsTimeStamp to ANSI C time_t.

Definition at line 933 of file epicsTime.cpp.

    {
        try {
            time_t_wrapper dst = epicsTime (*pSrc);
            *pDest = dst.ts;
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

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

Convert epicsTimeStamp to struct timespec

Definition at line 1008 of file epicsTime.cpp.

    {
        try {
            *pDest = epicsTime (*pSrc);
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

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

Convert epicsTimeStamp to struct timeval

Definition at line 1028 of file epicsTime.cpp.

    {
        try {
            *pDest = epicsTime (*pSrc);
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }

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

Convert epicsTimeStamp to struct tm in local time zone.

Definition at line 956 of file epicsTime.cpp.

    {
        try {
            local_tm_nano_sec tmns = epicsTime (*pSrc);
            *pDest = tmns.ansi_tm;
            if (pNSecDest)
                *pNSecDest = tmns.nSec;
        }
        catch (...) {
            return S_time_conversion;
        }
        return epicsTimeOK;
    }