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
andright
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
andright
, 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
equalsright
-
int epicsTimeNotEqual(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
left
not equal toright
-
int epicsTimeLessThan(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
left
was beforeright
-
int epicsTimeLessThanEqual(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
right
was no later thanleft
-
int epicsTimeGreaterThan(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
left
was afterright
-
int epicsTimeGreaterThanEqual(const epicsTimeStamp *pLeft, const epicsTimeStamp *pRight)
right
was not beforeleft
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 astruct tm
in the local timezone.
-
int epicsTime_gmtime(const time_t *clock, struct tm *result)
Break down a
time_t
into astruct 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.
-
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
-
epicsUInt32 secPastEpoch
-
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.
-
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).
-
struct time_t_wrapper
- #include <epicsTime.h>
C++ only ANSI C time_t.
This is for converting to/from the ANSI C
time_t
. Sincetime_t
is usually an elementary type providing a conversion operator fromtime_t
to/from epicsTime could cause undesirable implicit conversions. Providing a conversion operator to/from thetime_t_wrapper
instead prevents implicit conversions.Public Members
-
time_t ts
-
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.
Private Members
-
int eventNumber
-
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
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
Arithmetic operators
Standard operators involving epicsTime objects and time differences which are always expressed as a
double
in seconds.Comparison operators
Standard comparisons between epicsTime objects.
Public Types
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:This will print the current time in the format:epicsTime time = epicsTime::getCurrent(); char buf[30]; time.strftime(buf, 30, "%Y-%m-%d %H:%M:%S.%06f"); printf("%s\n", buf);
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.
Private Members
Private Static Functions
-
static void throwError(int code)
-
inline operator const epicsTimeStamp&() const