Home | History | Annotate | Line # | Download | only in include 
      1 /*	$NetBSD: timetoa.h,v 1.5 2020/05/25 20:47:20 christos Exp $	*/
      2 
      3 /*
      4  * timetoa.h -- time_t related string formatting
      5  *
      6  * Written by Juergen Perlinger (perlinger (at) ntp.org) for the NTP project.
      7  * The contents of 'html/copyright.html' apply.
      8  *
      9  * Printing a 'time_t' has some portability pitfalls, due to it's opaque
     10  * base type. The only requirement imposed by the standard is that it
     11  * must be a numeric type. For all practical purposes it's a signed int,
     12  * and 32 bits are common.
     13  *
     14  * Since the UN*X time epoch will cause a signed integer overflow for
     15  * 32-bit signed int values in the year 2038, implementations slowly
     16  * move to 64bit base types for time_t, even in 32-bit environments. In
     17  * such an environment sizeof(time_t) could be bigger than sizeof(long)
     18  * and the commonly used idiom of casting to long leads to truncation.
     19  *
     20  * As the printf() family has no standardised type specifier for time_t,
     21  * guessing the right output format specifier is a bit troublesome and
     22  * best done with the help of the preprocessor and "config.h".
     23  */
     24 #ifndef TIMETOA_H
     25 #define TIMETOA_H
     26 
     27 #include "ntp_fp.h"
     28 #include "ntp_stdlib.h"
     29 #include "ntp_unixtime.h"
     30 
     31 /*
     32  * Given the size of time_t, guess what can be used as an unsigned value
     33  * to hold a time_t and the printf() format specifcation.
     34  *
     35  * These should be used with the string constant concatenation feature
     36  * of the compiler like this:
     37  *
     38  * printf("a time stamp: %" TIME_FORMAT " and more\n", a_time_t_value);
     39  *
     40  * It's not exactly nice, but there's not much leeway once we want to
     41  * use the printf() family on time_t values.
     42  */
     43 
     44 #if SIZEOF_TIME_T <= SIZEOF_INT
     45 
     46 typedef unsigned int u_time;
     47 #define TIME_FORMAT "d"
     48 #define UTIME_FORMAT "u"
     49 
     50 #elif SIZEOF_TIME_T <= SIZEOF_LONG
     51 
     52 typedef unsigned long u_time;
     53 #define TIME_FORMAT "ld"
     54 #define UTIME_FORMAT "lu"
     55 
     56 #elif defined(SIZEOF_LONG_LONG) && SIZEOF_TIME_T <= SIZEOF_LONG_LONG
     57 
     58 typedef unsigned long long u_time;
     59 #define TIME_FORMAT "lld"
     60 #define UTIME_FORMAT "llu"
     61 
     62 #else
     63 #include "GRONK: what size has a time_t here?"
     64 #endif
     65 
     66 /*
     67  * general fractional time stamp formatting.
     68  *
     69  * secs - integral seconds of time stamp
     70  * frac - fractional units
     71  * prec - log10 of units per second (3=milliseconds, 6=microseconds,..)
     72  *	  or in other words: the count of decimal digits required.
     73  *	  If prec is < 0, abs(prec) is taken for the precision and secs
     74  *	  is treated as an unsigned value.
     75  *
     76  * The function will eventually normalise the fraction and adjust the
     77  * seconds accordingly.
     78  *
     79  * This function uses the string buffer library for the return value,
     80  * so do not keep the resulting pointers around.
     81  */
     82 extern const char *
     83 format_time_fraction(time_t secs, long frac, int prec);
     84 
     85 #endif /* !defined(TIMETOA_H) */
     86