Advanced Programming in

the UNIX Environment

Week 04, Segment 8:
time(3) is an illusion
Department of Computer Science
Stevens Institute of Technology

Jan Schaumann
[email protected]
https://stevens.netmeister.org/631/

 CS631 - Advanced Programming in the UNIX Environment

time(3)
#include <time.h>

time_t time(time_t *tloc);

Returns: time_t if OK, -1 on error

The time() function returns the value of time in seconds since 0 hours, 0 minutes, 0
seconds, January 1, 1970, Coordinated Universal Time.

(We already talked about the Y2K38 problem - see Week 01, Segment 3.)

2
Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06
 CS631 - Advanced Programming in the UNIX Environment

gettimeofday(2)
#include <sys/time.h>

int gettimeofday(struct timeval * restrict tp, void * restrict tzp);

Returns: 0 if OK, -1 on error

The system's notion of the current UTC time is obtained with the gettimeofday() call. The time
is expressed in seconds and microseconds since midnight (0 hour), January 1, 1970.

struct timeval {
time_t tv_sec; /* seconds */
suseconds_t tv_usec; /* and microseconds */
};
struct timezone {
int tz_minuteswest; /* of Greenwich */
int tz_dsttime; /* type of dst correction to apply */
}; 5
Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

clock_gettime(2)
#include <sys/time.h>

int clock_gettime(clockid_t clock_id, struct timespec *tp);

Returns: 0 if OK, -1 on error

The clock_gettime() function stores the time of the clock identified by clock_id into the
location specified by tp; clock_id CLOCK_REALTIME represents the amount of time
(in seconds and nanoseconds) since 00:00 Universal Coordinated Time, January 1,
1970.

7
Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

Breaking time using gmtime(3)

$ date +%s
1601230776
$ date
Sun Sep 27 18:19:37 UTC 2020

#include <time.h>

struct tm *gmtime(const time_t *clock);

Returns: pointer to struct_tm if OK, NULL on error

The gmtime() function converts to Coordinated Universal Time (UTC) and returns a
pointer to the tm structure described in tm(3).

9
Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

gmtime(3) and the struct tm

struct tm {
int tm_sec; /* seconds after the minute [0-61] */
int tm_min; /* minutes after the hour [0-59] */
int tm_hour; /* hours since midnight [0-23] */
int tm_mday; /* day of the month [1-31] */
int tm_mon; /* months since January [0-11] */
int tm_year; /* years since 1900 */
int tm_wday; /* days since Sunday [0-6] */
int tm_yday; /* days since January 1 [0-365] */
int tm_isdst; /* Daylight Savings Time flag */
};

10
Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

gmtime(3) and the struct tm

11
Jan Schaumann 2022-10-06
 CS631 - Advanced Programming in the UNIX Environment

Unix Epoch and leap seconds

1483228798 should be 'Sat Dec 31 23:59:58 2016'; is: Sat Dec 31 23:59:58 2016
1483228799 should be 'Sat Dec 31 23:59:59 2016'; is: Sat Dec 31 23:59:59 2016
1483228800 should be 'Sat Dec 31 23:59:60 2016'; is: Sun Jan 1 00:00:00 2017

Sat Dec 31 23:59:58 2016 should be 1483228798; is 1483228798

Sat Dec 31 23:59:59 2016 should be 1483228799; is 1483228799
Sat Dec 31 23:59:60 2016 should be 1483228800; is 1483228800
Sun Jan 1 00:00:00 2017 should be 1483228801; is 1483228800

struct tm {
int tm_sec; /* seconds after the minute [0-61] */
...
}

struct tm {
int tm_sec; /* Seconds. [0-60] (1 leap second) */
...
}
12
Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

gmtime(3) and the struct tm

$ date +%s
1601230776
$ date
Sun Sep 27 18:19:37 UTC 2020

#include <time.h>

struct tm *gmtime(const time_t *clock);

Returns: pointer to struct_tm if OK, NULL on error

The gmtime() function converts to Coordinated Universal Time (UTC) and returns a
pointer to the tm structure described in tm(3).

13
Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

gmtime(3) and the struct tm

$ date +%s
1601230776
$ date
Sun Sep 27 18:19:37 UTC 2020

#include <time.h>

struct tm *gmtime(const time_t *clock);

Returns: pointer to struct_tm if OK, NULL on error

char *asctime(const struct tm *tm);

Returns: string in "Thu Nov 24 18:22:48 1986\n\0" format if OK, NULL on error

14
Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

gmtime(3) and the struct tm

struct tm {
int tm_sec; /* seconds after the minute [0-61] */
int tm_min; /* minutes after the hour [0-59] */
int tm_hour; /* hours since midnight [0-23] */
int tm_mday; /* day of the month [1-31] */
int tm_mon; /* months since January [0-11] */
int tm_year; /* years since 1900 */
int tm_wday; /* days since Sunday [0-6] */
int tm_yday; /* days since January 1 [0-365] */
int tm_isdst; /* Daylight Savings Time flag */
};

16
Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

gmtime(3) and the struct tm

struct tm {
int tm_sec; /* seconds after the minute [0-61] */
int tm_min; /* minutes after the hour [0-59] */
int tm_hour; /* hours since midnight [0-23] */
int tm_mday; /* day of the month [1-31] */
int tm_mon; /* months since January [0-11] */
int tm_year; /* years since 1900 */
int tm_wday; /* days since Sunday [0-6] */
int tm_yday; /* days since January 1 [0-365] */
int tm_isdst; /* Daylight Savings Time flag */
long tm_gmtoff; /* offset from UTC in seconds */
__aconst char *tm_zone; /* timezone abbreviation */
};

17
Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

gmtime(3) and the struct tm

$ date +%s
1601240163
$ TZ=US/Easter date
Sun Sep 27 20:56:10 GMT 2020

#include <time.h>

struct tm *gmtime(const time_t *clock);

struct tm *localtime(const time_t *clock);
Returns: pointer to struct_tm if OK, NULL on error

char *asctime(const struct tm *tm);

Returns: string in "Thu Nov 24 18:22:48 1986\n\0" format if OK, NULL on error

18
Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06
Jan Schaumann 2022-10-06
Jan Schaumann 2022-10-06
Jan Schaumann 2022-10-06
 $ cd /usr/share/zoneinfo
$ find /usr/share/zoneinfo -type f \
$ for tz in $(find * -type f -name '[A-Z]*'); do
-name '[A-Z]*' -print | wc -l
> echo $tz
595
> TZ=$tz date
> echo
Jan Schaumann > done 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

mktime(3) and the struct tm

#include <time.h>

time_t mktime(struct tm *tm);

Returns: time_t if OK, -1 on error

char *ctime(const time_t *clock);

Returns: string like asctime(3) if OK, NULL on error

mktime(3) operates in the reverse direction from gmtime(3)/localtime(3).

ctime(3) is like asctime(3), but takes a time_t * instead of a struct tm *.

25
Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06

 CS631 - Advanced Programming in the UNIX Environment

gmtime(3) and the struct tm

$ date
Sun Sep 27 21:47:30 UTC 2020
$ date +%D
09/27/20
$ date +%Y-%m-%dT%H:%M:%SZ
2020-09-27T21:47:47Z

#include <time.h>

ssize_t strftime(char * restrict buf, size_t maxsize,

const char * restrict format, const struct tm * restrict timeptr);
Returns: number of characters placed into bu er

27
Jan Schaumann 2022-10-06

ff

Jan Schaumann 2022-10-06

Jan Schaumann 2022-10-06
 CS631 - Advanced Programming in the UNIX Environment

Links and Discussions

• https://www.iana.org/time-zones

• https://en.wikipedia.org/wiki/ISO_8601

• https://in niteundo.com/post/25326999628/falsehoods-programmers-believe-about-
time

• https://en.wikipedia.org/wiki/Coordinated_Universal_Time

• https://en.wikipedia.org/wiki/Leap_second

• http://hpiers.obspm.fr/eop-pc/products/bulletins/subscription.html

• https://pubs.opengroup.org/onlinepubs/9699919799/xrat/
V4_xbd_chap04.html#tag_21_04_16

• http://www.madore.org/~david/computers/unix-leap-seconds.html
30
Jan Schaumann 2022-10-06
fi