netwib doc_html (version 5.39.0)

## main index

## section index

    /*-------------------------------------------------------------*/
    /***************************************************************
     * A netwib_time contains a time duration (relative time) or a *
     * date (absolute time).                                       *
     * Fields of a netwib_time can be directly used, but when it is*
     * set nsec must be between 0 and 999999999.                   *
     ***************************************************************/

    /*-------------------------------------------------------------*/
    typedef struct {
      netwib_uint32 sec;  /* seconds */
      netwib_uint32 nsec; /* nanoseconds */
    } netwib_time;
    typedef const netwib_time netwib_consttime;

    /*-------------------------------------------------------------*/
    /***************************************************************
     * Every function should be prepared to receive as input :     *
     *  - netwib_time*                                             *
     *  - NETWIB_TIME_ZERO                                         *
     *  - NETWIB_TIME_INFINITE                                     *
     * However, NETWIB_TIME_ZERO and NETWIB_TIME_INFINITE cannot be*
     * returned as output by a function. Those defines exist to    *
     * quickly specify those specific inputs.                      *
     ***************************************************************/
    /* Empty time duration or year 1970 */
    #define NETWIB_TIME_ZERO ((netwib_time*)1)
    /* Infinite time duration or year 2038/2108 */
    #define NETWIB_TIME_INFINITE ((netwib_time*)2)

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_init_time
       Description :
         Initialize a netwib_time from another netwib_time.
         This function is mainly useful to convert
         NETWIB_TIME_ZERO or NETWIB_TIME_INFINITE to a real structure.
       Input parameter(s) :
         ptimein : time to copy
       Input/output parameter(s) :
       Output parameter(s) :
         *ptimeout : netwib_time set
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_init_time(netwib_consttime *ptimein,
                                     netwib_time *ptimeout);

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_init_fields
       Description :
         Initialize a netwib_time.
       Input parameter(s) :
         sec : number of seconds
         msec : number of milliseconds
         usec : number of microseconds
         nsec : number of nanoseconds
       Input/output parameter(s) :
       Output parameter(s) :
         *ptime : netwib_time set
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_init_fields(netwib_uint32 sec,
                                       netwib_uint32 msec,
                                       netwib_uint32 usec,
                                       netwib_uint32 nsec,
                                       netwib_time *ptime);
    #define netwib_time_init_sec(sec,ptime) netwib_time_init_fields(sec,0,0,0,ptime)
    #define netwib_time_init_msec(msec,ptime) netwib_time_init_fields(0,msec,0,0,ptime)
    #define netwib_time_init_usec(usec,ptime) netwib_time_init_fields(0,0,usec,0,ptime)
    #define netwib_time_init_nsec(nsec,ptime) netwib_time_init_fields(0,0,0,nsec,ptime)

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_decode_xyz
       Description :
         Obtain time values stored in a netwib_time.
           function                 obtained ranges
           netwib_time_decode_sec    [0..2^32]
           netwib_time_decode_msec   [0..2^32]
           netwib_time_decode_usec   [0..2^32]
           netwib_time_decode_nsec   [0..2^32]
           netwib_time_decode_fields [0..2^32], [0-999], [0-999], [0-999]
       Input parameter(s) :
         *ptime : netwib_time
       Input/output parameter(s) :
       Output parameter(s) :
         *psec : seconds
         *pmsec : milliseconds
         *pusec : microseconds
         *pnsec : nanoseconds
       Normal return values :
         NETWIB_ERR_OK : ok
         NETWIB_ERR_NOTCONVERTED : too big to be decoded
    */
    netwib_err netwib_time_decode_fields(netwib_consttime *ptime,
                                         netwib_uint32 *psec,
                                         netwib_uint32 *pmsec,
                                         netwib_uint32 *pusec,
                                         netwib_uint32 *pnsec);
    netwib_err netwib_time_decode_sec(netwib_consttime *ptime,
                                      netwib_uint32 *psec);
    netwib_err netwib_time_decode_msec(netwib_consttime *ptime,
                                       netwib_uint32 *pmsec);
    netwib_err netwib_time_decode_usec(netwib_consttime *ptime,
                                       netwib_uint32 *pusec);
    netwib_err netwib_time_decode_nsec(netwib_consttime *ptime,
                                       netwib_uint32 *pnsec);

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_plus_time
       Description :
         Initialize a netwib_time by adding two netwib_time.
       Input parameter(s) :
         ptimetoadd : time to add
       Input/output parameter(s) :
         *ptime : netwib_time incremented by ptime
       Output parameter(s) :
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_plus_time(netwib_time *ptime,
                                     netwib_consttime *ptimetoadd);
    netwib_err netwib_time_plus_fields(netwib_time *ptime,
                                       netwib_uint32 sec,
                                       netwib_uint32 msec,
                                       netwib_uint32 usec,
                                       netwib_uint32 nsec);
    #define netwib_time_plus_sec(ptime,sec) netwib_time_plus_fields(ptime,sec,0,0,0)
    #define netwib_time_plus_msec(ptime,msec) netwib_time_plus_fields(ptime,0,msec,0,0)
    #define netwib_time_plus_usec(ptime,usec) netwib_time_plus_fields(ptime,0,0,usec,0)
    #define netwib_time_plus_nsec(ptime,nsec) netwib_time_plus_fields(ptime,0,0,0,nsec)

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_minus_time
       Description :
         Initialize a netwib_time by adding two netwib_time.
       Input parameter(s) :
         ptimetoadd : time to add
       Input/output parameter(s) :
         *ptime : netwib_time incremented by ptime
       Output parameter(s) :
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_minus_time(netwib_time *ptime,
                                      netwib_consttime *ptimetosub);
    netwib_err netwib_time_minus_fields(netwib_time *ptime,
                                        netwib_uint32 sec,
                                        netwib_uint32 msec,
                                        netwib_uint32 usec,
                                        netwib_uint32 nsec);
    #define netwib_time_minus_sec(ptime,sec) netwib_time_minus_fields(ptime,sec,0,0,0)
    #define netwib_time_minus_msec(ptime,msec) netwib_time_minus_fields(ptime,0,msec,0,0)
    #define netwib_time_minus_usec(ptime,usec) netwib_time_minus_fields(ptime,0,0,usec,0)
    #define netwib_time_minus_nsec(ptime,nsec) netwib_time_minus_fields(ptime,0,0,0,nsec)

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_cmp
       Description :
         Compare two netwib_time.
       Input parameter(s) :
         ptime1 : time
         ptime2 : time
       Input/output parameter(s) :
       Output parameter(s) :
         *pcmp :
           - if time1<time2, *pcmp is set to NETWIB_CMP_LT
           - if time1>time2, *pcmp is set to NETWIB_CMP_GT
           - if time1==time2, *pcmp is set to NETWIB_CMP_EQ
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_cmp(netwib_consttime *ptime1,
                               netwib_consttime *ptime2,
                               netwib_cmp *pcmp);

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_sleep_xyz
       Description :
         Sleep for a time duration.
         This is not a "real time" sleep. This sleep is not precise.
         On some systems, the duration might exceed the wanted time
         by several milliseconds.
       Input parameter(s) :
         *preltime : relative time
         sec : number of seconds to wait
         msec : number of milliseconds to wait
         usec : number of microseconds to wait
       Input/output parameter(s) :
       Output parameter(s) :
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_sleep_time(netwib_consttime *preltime);
    netwib_err netwib_time_sleep_fields(netwib_uint32 sec,
                                        netwib_uint32 msec,
                                        netwib_uint32 usec,
                                        netwib_uint32 nsec);
    #define netwib_time_sleep_sec(sec) netwib_time_sleep_fields(sec,0,0,0)
    #define netwib_time_sleep_msec(msec) netwib_time_sleep_fields(0,msec,0,0)
    #define netwib_time_sleep_usec(usec) netwib_time_sleep_fields(0,0,usec,0)
    #define netwib_time_sleep_nsec(nsec) netwib_time_sleep_fields(0,0,0,nsec)

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_wait_time
       Description :
         Wait an absolute time value.
         This is not a "real time" wait. This wait is not precise.
         On some systems, the duration might exceed the wanted time
         by several milliseconds.
       Input parameter(s) :
         *pabstime : absolute time (from 1970)
       Input/output parameter(s) :
       Output parameter(s) :
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_wait_time(netwib_consttime *pabstime);

    /*-------------------------------------------------------------*/
    typedef enum {
      NETWIB_TIME_ENCODETYPE_NOTHING = 1, /* print nothing */
      NETWIB_TIME_ENCODETYPE_BEST,        /* best display of the form :
                                             2d:3h:4m:5s:6ms:7us:8ns*/
      NETWIB_TIME_ENCODETYPE_BEST2,       /* best display of the form :
                                             2 days 3 hours 4 minutes ...*/
      NETWIB_TIME_ENCODETYPE_SEC,         /* "123s" */
      NETWIB_TIME_ENCODETYPE_SEC2,        /* "123 second(s)" */
      NETWIB_TIME_ENCODETYPE_MSEC,        /* "123ms" */
      NETWIB_TIME_ENCODETYPE_MSEC2,       /* "123 millisecond(s)" */
      NETWIB_TIME_ENCODETYPE_USEC,        /* "123us" */
      NETWIB_TIME_ENCODETYPE_USEC2,       /* "123 microsecond(s)" */
      NETWIB_TIME_ENCODETYPE_NSEC,        /* "123ns" */
      NETWIB_TIME_ENCODETYPE_NSEC2        /* "123 nanosecond(s)" */
    } netwib_time_encodetype;

    /*-------------------------------------------------------------*/
    /* Name : netwib_buf_append_time
       Description :
         Append a string representing a netwib_time duration (relative
         time). To display an absolute time, use function
         netwib_time_decode_localtime.
       Input parameter(s) :
         *ptime : time to print
         encodetype : netwib_time_encodetype to use
       Input/output parameter(s) :
       Output parameter(s) :
         pbuf : buffer updated
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_buf_append_time(netwib_consttime *preltime,
                                      netwib_time_encodetype encodetype,
                                      netwib_buf *pbuf);

    /*-------------------------------------------------------------*/
    typedef struct {
      netwib_uint32 nsec; /* nanoseconds [0-999999999]*/
      netwib_int32 sec; /* seconds [0-59] */
      netwib_int32 min; /* minutes [0-59] */
      netwib_int32 hour; /* hours [0-23] */
      netwib_int32 mday; /* day [1-31] */
      netwib_int32 mon; /* month [1-12] (!= from struct tm) */
      netwib_uint32 year; /* year (start at 0) (!= from struct tm) */
      netwib_uint32 wday; /* day of the week [0(sun)-6(sat)] */
      netwib_uint32 yday; /* day of the year [1-365/366] (!= from struct tm) */
      netwib_int32 zoneoffset; /* offset in seconds between localtime
                                  and GMT (for example GMT+1 is
                                  +3600). This field is used only by
                                  netwib_time_decode_localtime */
    } netwib_localtime;
    typedef const netwib_localtime netwib_constlocaltime;

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_init_now
       Description :
         Initialize a netwib_time with the current UTC/GMT time.
         It uses the number of seconds elapsed since 00:00:00 on
         January 1, 1970, Coordinated Universal Time (UTC)
       Input parameter(s) :
       Input/output parameter(s) :
       Output parameter(s) :
         *ptime : netwib_time set to the current time (absolute time)
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_init_now(netwib_time *pabstime);

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_init_localtime
       Description :
         Initialize a netwib_time using localtime fields
       Input parameter(s) :
         *plocaltime : structure containing day. Fields nsec, wday,
                       and yday are ignored. Other fields
                       are normalized before converting.
       Input/output parameter(s) :
       Output parameter(s) :
         *ptime : netwib_time set to the current local time
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_init_localtime(netwib_constlocaltime *plocaltime,
                                          netwib_time *pabstime);

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_decode_localtime
       Description :
         Initialize a netwib_localtime using time fields
       Input parameter(s) :
         *ptime : structure containing current time (UTC)
       Input/output parameter(s) :
       Output parameter(s) :
         *plocaltime : netwib_localtime set
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_decode_localtime(netwib_consttime *pabstime,
                                            netwib_localtime *plocaltime);

    /*-------------------------------------------------------------*/
    typedef enum {
      NETWIB_LOCALTIME_ENCODETYPE_NOTHING = 1, /* print nothing */
      NETWIB_LOCALTIME_ENCODETYPE_NSEC_ZERO,   /* 000000000-999999999 */
      NETWIB_LOCALTIME_ENCODETYPE_NSEC_SPACE,  /* ________0-999999999 */
      NETWIB_LOCALTIME_ENCODETYPE_SEC_ZERO,    /* 00-59 */
      NETWIB_LOCALTIME_ENCODETYPE_SEC_SPACE,   /* _0-59 */
      NETWIB_LOCALTIME_ENCODETYPE_MIN_ZERO,    /* 00-59 */
      NETWIB_LOCALTIME_ENCODETYPE_MIN_SPACE,   /* _0-59 */
      NETWIB_LOCALTIME_ENCODETYPE_HOUR_ZERO,   /* 00-23 */
      NETWIB_LOCALTIME_ENCODETYPE_HOUR_SPACE,  /* _0-23 */
      NETWIB_LOCALTIME_ENCODETYPE_MDAY_ZERO,   /* 01-31 */
      NETWIB_LOCALTIME_ENCODETYPE_MDAY_SPACE,  /* _1-31 */
      NETWIB_LOCALTIME_ENCODETYPE_MON_ZERO,    /* 01-12 */
      NETWIB_LOCALTIME_ENCODETYPE_MON_SPACE,   /* _1-12 */
      NETWIB_LOCALTIME_ENCODETYPE_MON_SHORT,   /* Jan */
      NETWIB_LOCALTIME_ENCODETYPE_MON_LONG,    /* January */
      NETWIB_LOCALTIME_ENCODETYPE_YEAR_SHORT,  /* 04 */
      NETWIB_LOCALTIME_ENCODETYPE_YEAR_LONG,   /* 2004 */
      NETWIB_LOCALTIME_ENCODETYPE_WDAY_SHORT,  /* Mon */
      NETWIB_LOCALTIME_ENCODETYPE_WDAY_LONG,   /* Monday */
      NETWIB_LOCALTIME_ENCODETYPE_YDAY_ZERO,   /* 001-365 */
      NETWIB_LOCALTIME_ENCODETYPE_YDAY_SPACE,  /* __1-365 */
      NETWIB_LOCALTIME_ENCODETYPE_ZONE_SEC,    /* +3600 */
      NETWIB_LOCALTIME_ENCODETYPE_ZONE_GMT,    /* GMT+1 */
      NETWIB_LOCALTIME_ENCODETYPE_ZONE_HM,     /* +0100 */
    } netwib_localtime_encodetype;

    /*-------------------------------------------------------------*/
    /* Name : netwib_buf_append_localtime
       Description :
         Append a string representing a field of a netwib_localtime.
       Input parameter(s) :
         *plocaltime : localtime to print
         encodetype : netwib_localtime_encodetype to use
       Input/output parameter(s) :
       Output parameter(s) :
         pbuf : buffer updated
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_buf_append_localtime(netwib_constlocaltime *plocaltime,
                                           netwib_localtime_encodetype encodetype,
                                           netwib_buf *pbuf);

    /*-------------------------------------------------------------*/
    /* Name : netwib_time_iselapsed
       Description :
         Check if an absolute time has elapsed.
       Input parameter(s) :
         *ptime : time
       Input/output parameter(s) :
       Output parameter(s) :
         *pyes : true if elapsed or equal
       Normal return values :
         NETWIB_ERR_OK : ok
    */
    netwib_err netwib_time_iselapsed(netwib_consttime *pabstime,
                                     netwib_bool *pyes);

## main index

## section index