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@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
46typedef unsigned int u_time;
47#define TIME_FORMAT "d"
48#define UTIME_FORMAT "u"
49
50#elif SIZEOF_TIME_T <= SIZEOF_LONG
51
52typedef 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
58typedef 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 */
82extern const char *
83format_time_fraction(time_t secs, long frac, int prec);
84
85#endif /* !defined(TIMETOA_H) */
86