diff -r 0181578dc746 Doc/library/time.rst --- a/Doc/library/time.rst Thu Dec 22 10:02:28 2016 -0800 +++ b/Doc/library/time.rst Thu Dec 22 23:48:07 2016 -0500 @@ -19,9 +19,16 @@ .. index:: single: epoch -* The :dfn:`epoch` is the point where the time starts. On January 1st of that - year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is - 1970. To find out what the epoch is, look at ``gmtime(0)``. +* The :dfn:`epoch` is the point where the time starts, and is platform + dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC). + To find out what the epoch is on a given platform, look at ``gmtime(0)``. + +.. index:: seconds since the epoch + +* The term :dfn:`seconds since the epoch` typically refers to the total number + of elapsed seconds since the epoch excluding + `leap seconds `_. On all + POSIX-compliant platforms leap seconds are excluded from this total. .. index:: single: Year 2038 @@ -572,12 +579,19 @@ .. function:: time() - Return the time in seconds since the epoch as a floating point number. + Return the time in seconds since the epoch as a floating point + number. The specific date of the epoch and the handling of + `leap seconds `_ + is platform dependent. + On Windows and most Unix systems, the epoch is January 1, 1970, + 00:00:00 (UTC) and leap seconds are not counted towards the time + in seconds since the epoch. This is commonly referred to as + `Unix time `_. Note that even though the time is always returned as a floating point number, not all systems provide time with a better precision than 1 second. While this function normally returns non-decreasing values, it can return a - lower value than a previous call if the system clock has been set back between - the two calls. + lower value than a previous call if the system clock has been set back + between the two calls. .. data:: timezone