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 <stdexcept>
#include <ostream>

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...
struct	local_tm_nano_sec
	C++ only ANSI C struct tm with nanoseconds, local timezone. More...
struct	gm_tm_nano_sec
	C++ only ANSI C sruct tm with nanoseconds, UTC. More...
struct	time_t_wrapper
	C++ only ANSI C time_t. More...
class	epicsTimeEvent
	C++ Event number wrapper class. More...
class	epicsTime
	C++ time stamp object. More...

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

Typedefs
typedef epicsUInt64	epicsUTag
	Type of UTAG field (dbCommon::utag)

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()
LIBCOM_API void epicsStdCall	epicsTimeShow (const epicsTimeStamp *, unsigned interestLevel)
	Dump current state to stdout.
LIBCOM_API std::ostream &	operator<< (std::ostream &strm, const epicsTime &ts)
generalTime functions
These are implemented in the "generalTime" framework:
LIBCOM_API int epicsStdCall	epicsTimeGetCurrent (epicsTimeStamp *pDest)
	Get current time into *pDest.
LIBCOM_API int epicsStdCall	epicsTimeGetEvent (epicsTimeStamp *pDest, int eventNumber)
	Get time of event eventNumber into *pDest.
LIBCOM_API 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.
LIBCOM_API int	epicsTimeGetCurrentInt (epicsTimeStamp *pDest)
	Get current time into *pDest (ISR-safe)
LIBCOM_API 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
LIBCOM_API int epicsStdCall	epicsTimeToTime_t (time_t *pDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to ANSI C time_t.
LIBCOM_API int epicsStdCall	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
LIBCOM_API int epicsStdCall	epicsTimeToTM (struct tm *pDest, unsigned long *pNSecDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to struct tm in local time zone.
LIBCOM_API int epicsStdCall	epicsTimeToGMTM (struct tm *pDest, unsigned long *pNSecDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to struct tm in UTC/GMT.
LIBCOM_API int epicsStdCall	epicsTimeFromTM (epicsTimeStamp *pDest, const struct tm *pSrc, unsigned long nSecSrc)
	Set epicsTimeStamp from struct tm in local time zone.
LIBCOM_API int epicsStdCall	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.
LIBCOM_API int epicsStdCall	epicsTimeToTimespec (struct timespec *pDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to struct timespec
LIBCOM_API int epicsStdCall	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.
LIBCOM_API int epicsStdCall	epicsTimeToTimeval (struct timeval *pDest, const epicsTimeStamp *pSrc)
	Convert epicsTimeStamp to struct timeval
LIBCOM_API int epicsStdCall	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.
LIBCOM_API double epicsStdCall	epicsTimeDiffInSeconds (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	Time difference between left and right in seconds.
LIBCOM_API void epicsStdCall	epicsTimeAddSeconds (epicsTimeStamp *pDest, double secondsToAdd)
	Add some number of seconds to dest.
LIBCOM_API epicsInt64 epicsStdCall	epicsTimeDiffInNS (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	Time difference between left and right, as a signed integer number of nanoseconds.
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
LIBCOM_API int epicsStdCall	epicsTimeNotEqual (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	left not equal to right
LIBCOM_API int epicsStdCall	epicsTimeLessThan (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	left was before right
LIBCOM_API int epicsStdCall	epicsTimeLessThanEqual (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	right was no later than left
LIBCOM_API int epicsStdCall	epicsTimeGreaterThan (const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
	left was after right
LIBCOM_API int epicsStdCall	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
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.
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.
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.
LIBCOM_API epicsUInt64	epicsMonotonicGet (void)
	Fetch monotonic counter, returns the number of nanoseconds since some unspecified time.

Detailed Description

Author

Jeffrey O. Hill

Definition in file epicsTime.h.

Macro Definition Documentation

POSIX_TIME_AT_EPICS_EPOCH

#define POSIX_TIME_AT_EPICS_EPOCH   631152000u

Definition at line 27 of file epicsTime.h.

TS_STAMP

#define TS_STAMP   epicsTimeStamp

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 55 of file epicsTime.h.

epicsTimeOK

#define epicsTimeOK   0

Definition at line 81 of file epicsTime.h.

S_time_noProvider

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

Definition at line 83 of file epicsTime.h.

S_time_badEvent

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

Definition at line 85 of file epicsTime.h.

S_time_badArgs

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

Definition at line 87 of file epicsTime.h.

S_time_noMemory

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

Definition at line 89 of file epicsTime.h.

S_time_unsynchronized

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

Definition at line 91 of file epicsTime.h.

S_time_timezone

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

Definition at line 93 of file epicsTime.h.

S_time_conversion

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

Definition at line 95 of file epicsTime.h.

epicsTimeEventCurrentTime

#define epicsTimeEventCurrentTime   0

Definition at line 102 of file epicsTime.h.

epicsTimeEventBestTime

#define epicsTimeEventBestTime   -1

Definition at line 103 of file epicsTime.h.

epicsTimeEventDeviceTime

#define epicsTimeEventDeviceTime   -2

Definition at line 104 of file epicsTime.h.

Typedef Documentation

epicsUTag

typedef epicsUInt64 epicsUTag

Definition at line 49 of file epicsTime.h.

Function Documentation

epicsTimeDiffInNS()

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

Since

EPICS 7.0.6.1