epicsTime.h

Go to the documentation of this file.

/*************************************************************************\
* Copyright (c) 2009 UChicago Argonne LLC, as Operator of Argonne
*     National Laboratory.
* Copyright (c) 2002 The Regents of the University of California, as
*     Operator of Los Alamos National Laboratory.
* SPDX-License-Identifier: EPICS
* EPICS BASE is distributed subject to a Software License Agreement found
* in file LICENSE that is included with this distribution.
\*************************************************************************/
#ifndef epicsTimehInclude
#define epicsTimehInclude

#include <time.h>

#include "libComAPI.h"
#include "epicsTypes.h"
#include "osdTime.h"
#include "errMdef.h"

#define POSIX_TIME_AT_EPICS_EPOCH 631152000u

typedef struct epicsTimeStamp {
    epicsUInt32    secPastEpoch;   
    epicsUInt32    nsec;           
} epicsTimeStamp;

#define TS_STAMP epicsTimeStamp


struct timespec; /* POSIX real time */

struct timeval; /* BSD */

struct l_fp; /* NTP timestamp */

#ifdef __cplusplus

struct local_tm_nano_sec {
    struct tm ansi_tm;  
    unsigned long nSec; 
};

struct gm_tm_nano_sec {
    struct tm ansi_tm; 
    unsigned long nSec; 
};

struct time_t_wrapper {
    time_t ts;
};

class LIBCOM_API epicsTimeEvent
{
public:
    epicsTimeEvent (const int &number); 
    operator int () const;              
private:
    int eventNumber;
};

class LIBCOM_API epicsTime
{
public:
    class unableToFetchCurrentTime {};
    class formatProblemWithStructTM {};

    epicsTime ();

    static epicsTime getEvent ( const epicsTimeEvent & );
    static epicsTime getCurrent ();
    static epicsTime getMonotonic ();

    operator epicsTimeStamp () const;
    epicsTime ( const epicsTimeStamp & ts );
    epicsTime & operator = ( const epicsTimeStamp & );
    operator time_t_wrapper () const;
    epicsTime ( const time_t_wrapper & );
    epicsTime & operator = ( const time_t_wrapper & );
    operator local_tm_nano_sec () const;
    epicsTime ( const local_tm_nano_sec & );
    epicsTime & operator = ( const local_tm_nano_sec & );
    operator gm_tm_nano_sec () const;
    epicsTime ( const gm_tm_nano_sec & );
    epicsTime & operator = ( const gm_tm_nano_sec & );
    operator struct timespec () const;
    epicsTime ( const struct timespec & );
    epicsTime & operator = ( const struct timespec & );
    operator struct timeval () const;
    epicsTime ( const struct timeval & );
    epicsTime & operator = ( const struct timeval & );
    operator l_fp () const;
    epicsTime ( const l_fp & );
    epicsTime & operator = ( const l_fp & );
    operator struct _FILETIME () const;
    epicsTime ( const struct _FILETIME & );
    epicsTime & operator = ( const struct _FILETIME & );
    double operator- ( const epicsTime & ) const;
    epicsTime operator+ ( const double & ) const;
    epicsTime operator- ( const double & ) const;
    epicsTime operator+= ( const double & );
    epicsTime operator-= ( const double & );
     bool operator == ( const epicsTime & ) const;
     bool operator != ( const epicsTime & ) const;
     bool operator <= ( const epicsTime & ) const;
     bool operator < ( const epicsTime & ) const;
     bool operator >= ( const epicsTime & ) const;
     bool operator > ( const epicsTime & ) const;
    size_t strftime ( char * pBuff, size_t bufLength, const char * pFormat ) const;

    void show ( unsigned interestLevel ) const;

private:
    /*
     * private because:
     * a) application does not break when EPICS epoch is changed
     * b) no assumptions about internal storage or internal precision
     * in the application
     * c) it would be easy to forget which argument is nanoseconds
     * and which argument is seconds (no help from compiler)
     */
    epicsTime ( const unsigned long secPastEpoch, const unsigned long nSec );
    void addNanoSec ( long nanoSecAdjust );

    unsigned long secPastEpoch; /* seconds since O000 Jan 1, 1990 */
    unsigned long nSec; /* nanoseconds within second */
};

extern "C" {
#endif /* __cplusplus */

#define epicsTimeOK 0

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

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

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

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

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

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

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

#define epicsTimeEventCurrentTime 0
#define epicsTimeEventBestTime -1
#define epicsTimeEventDeviceTime -2

LIBCOM_API int epicsStdCall epicsTimeGetCurrent ( epicsTimeStamp * pDest );
LIBCOM_API int epicsStdCall epicsTimeGetEvent (
    epicsTimeStamp *pDest, int eventNumber);
LIBCOM_API int epicsTimeGetMonotonic ( epicsTimeStamp * pDest );
LIBCOM_API int epicsTimeGetCurrentInt(epicsTimeStamp *pDest);
LIBCOM_API int epicsTimeGetEventInt(epicsTimeStamp *pDest, int eventNumber);
LIBCOM_API int epicsStdCall epicsTimeToTime_t (
    time_t * pDest, const epicsTimeStamp * pSrc );
LIBCOM_API int epicsStdCall epicsTimeFromTime_t (
    epicsTimeStamp * pDest, time_t src );
LIBCOM_API int epicsStdCall epicsTimeToTM (
    struct tm * pDest, unsigned long * pNSecDest, const epicsTimeStamp * pSrc );
LIBCOM_API int epicsStdCall epicsTimeToGMTM (
    struct tm * pDest, unsigned long * pNSecDest, const epicsTimeStamp * pSrc );
LIBCOM_API int epicsStdCall epicsTimeFromTM (
    epicsTimeStamp * pDest, const struct tm * pSrc, unsigned long nSecSrc );
LIBCOM_API int epicsStdCall epicsTimeFromGMTM (
    epicsTimeStamp * pDest, const struct tm * pSrc, unsigned long nSecSrc );
LIBCOM_API int epicsStdCall epicsTimeToTimespec (
    struct timespec * pDest, const epicsTimeStamp * pSrc );
LIBCOM_API int epicsStdCall epicsTimeFromTimespec (
    epicsTimeStamp * pDest, const struct timespec * pSrc );
LIBCOM_API int epicsStdCall epicsTimeToTimeval (
    struct timeval * pDest, const epicsTimeStamp * pSrc );
LIBCOM_API int epicsStdCall epicsTimeFromTimeval (
    epicsTimeStamp * pDest, const struct timeval * pSrc );
LIBCOM_API double epicsStdCall epicsTimeDiffInSeconds (
    const epicsTimeStamp * pLeft, const epicsTimeStamp * pRight );/* left - right */
LIBCOM_API void epicsStdCall epicsTimeAddSeconds (
    epicsTimeStamp * pDest, double secondsToAdd ); /* adds seconds to *pDest */
LIBCOM_API int epicsStdCall epicsTimeEqual (
    const epicsTimeStamp * pLeft, const epicsTimeStamp * pRight);
LIBCOM_API int epicsStdCall epicsTimeNotEqual (
    const epicsTimeStamp * pLeft, const epicsTimeStamp * pRight);
LIBCOM_API int epicsStdCall epicsTimeLessThan (
    const epicsTimeStamp * pLeft, const epicsTimeStamp * pRight);
LIBCOM_API int epicsStdCall epicsTimeLessThanEqual (
    const epicsTimeStamp * pLeft, const epicsTimeStamp * pRight);
LIBCOM_API int epicsStdCall epicsTimeGreaterThan (
    const epicsTimeStamp * pLeft, const epicsTimeStamp * pRight);
LIBCOM_API int epicsStdCall epicsTimeGreaterThanEqual (
    const epicsTimeStamp * pLeft, const epicsTimeStamp * pRight);
LIBCOM_API size_t epicsStdCall epicsTimeToStrftime (
    char * pBuff, size_t bufLength, const char * pFormat, const epicsTimeStamp * pTS );

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

LIBCOM_API int epicsStdCall epicsTime_localtime ( const time_t * clock, struct tm * result );
LIBCOM_API int epicsStdCall epicsTime_gmtime ( const time_t * clock, struct tm * result );
LIBCOM_API epicsUInt64 epicsMonotonicResolution(void);
LIBCOM_API epicsUInt64 epicsMonotonicGet(void);
#ifdef EPICS_EXPOSE_LIBCOM_MONOTONIC_PRIVATE
LIBCOM_API void osdMonotonicInit(void);
#endif

#ifdef __cplusplus
}
#endif /* __cplusplus */

/* inline member functions ,*/
#ifdef __cplusplus

/* epicsTimeEvent */

inline epicsTimeEvent::epicsTimeEvent (const int &number) :
    eventNumber(number) {}

inline epicsTimeEvent::operator int () const
{
    return this->eventNumber;
}


/* epicsTime */

inline epicsTime epicsTime::operator - ( const double & rhs ) const
{
    return epicsTime::operator + ( -rhs );
}

inline epicsTime epicsTime::operator += ( const double & rhs )
{
    *this = epicsTime::operator + ( rhs );
    return *this;
}

inline epicsTime epicsTime::operator -= ( const double & rhs )
{
    *this = epicsTime::operator + ( -rhs );
    return *this;
}

inline bool epicsTime::operator == ( const epicsTime & rhs ) const
{
    if ( this->secPastEpoch == rhs.secPastEpoch && this->nSec == rhs.nSec ) {
        return true;
    }
    return false;
}

inline bool epicsTime::operator != ( const epicsTime & rhs ) const
{
    return !epicsTime::operator == ( rhs );
}

inline bool epicsTime::operator >= ( const epicsTime & rhs ) const
{
    return ! ( *this < rhs );
}

inline bool epicsTime::operator > ( const epicsTime & rhs ) const
{
    return ! ( *this <= rhs );
}

inline epicsTime & epicsTime::operator = ( const local_tm_nano_sec & rhs )
{
    return *this = epicsTime ( rhs );
}

inline epicsTime & epicsTime::operator = ( const gm_tm_nano_sec & rhs )
{
    return *this = epicsTime ( rhs );
}

inline epicsTime & epicsTime::operator = ( const struct timespec & rhs )
{
    *this = epicsTime ( rhs );
    return *this;
}

inline epicsTime & epicsTime::operator = ( const epicsTimeStamp & rhs )
{
    *this = epicsTime ( rhs );
    return *this;
}

inline epicsTime & epicsTime::operator = ( const l_fp & rhs )
{
    *this = epicsTime ( rhs );
    return *this;
}

inline epicsTime & epicsTime::operator = ( const time_t_wrapper & rhs )
{
    *this = epicsTime ( rhs );
    return *this;
}
#endif /* __cplusplus */

#endif /* epicsTimehInclude */