Rollup merge of #109660 - ijackson:leap, r=thomcc

Document that SystemTime does not count leap seconds

Fixes #77994

This may not be entirely uncontroversial.  I know that `@Ekleog` is going to disagree.  However, in support of this docs change:

 This documents the current behaviour.  The alternative would be to plan to *change* the behaviour.

There are many programs which need to get a POSIX time (a `time_t`).  Right now, `duration_since(UNIX_EPOCH)` is the only facility in std that does that.  So, that is what programs use.  Changing the behaviour would  break[1] all of those programs.  We would need to define a new API that can be used to get a POSIX time, and get everyone to use it.  This seems highly unpalatable.

And, even if we wanted to do that, time with leap seconds is a lot less easy to work with.  We would need to arrange to have a leap seconds table available to `std` somehow, and make sure that it was kept up to date.  Currently we don't offer to do that for timezone data, which has similar needs.  There are other complications.  So it seems it would be awkwarrd to *implement* a facility that provides time including leap seconds, and the resulting value would be hard for applications to work with.

Therefore, I think it's clear that we don't want to plan to ever change `SystemTime`.  We should plan to keep it the way it is.  Providing TAI (for example) should be left to external crates, or additional APIs we may add in the future.

For more discussion see #77994 and in particular `@fanf2's` https://github.com/rust-lang/rust/issues/77994#issuecomment-1409448174

[1]  Of course, by "break" we really only mean *future* breakage in the case where there is, in fact, ever another leap second.  There may well not be: they are in the process of being abolished (although this is of course being contested).  But if we decide that `SystemTime::now().duraton_since(UNIX_EPOCH)` counts leap seconds, it would start to return `Durations`s that are 27s different to the current answers.   That's clearly unacceptable.  And we can hardly change `UNIX_EPOCH` by 27s.

library/std/src/time.rs

@@ -176,6 +176,14 @@ pub struct Instant(time::Instant);
 /// The size of a `SystemTime` struct may vary depending on the target operating
 /// system.
 ///
+/// A `SystemTime` does not count leap seconds.
+/// `SystemTime::now()`'s behaviour around a leap second
+/// is the same as the operating system's wall clock.
+/// The precise behaviour near a leap second
+/// (e.g. whether the clock appears to run slow or fast, or stop, or jump)
+/// depends on platform and configuration,
+/// so should not be relied on.
+///
 /// Example:
 ///
 /// ```no_run
@@ -461,6 +469,9 @@ impl fmt::Debug for Instant {
 impl SystemTime {
     /// An anchor in time which can be used to create new `SystemTime` instances or
     /// learn about where in time a `SystemTime` lies.
+    //
+    // NOTE! this documentation is duplicated, here and in std::time::UNIX_EPOCH.
+    // The two copies are not quite identical, because of the difference in naming.
     ///
     /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
     /// respect to the system clock. Using `duration_since` on an existing
@@ -468,6 +479,11 @@ impl SystemTime {
     /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
     /// `SystemTime` instance to represent another fixed point in time.
     ///
+    /// `duration_since(UNIX_EPOCH).unwrap().as_secs()` returns
+    /// the number of non-leap seconds since the start of 1970 UTC.
+    /// This is a POSIX `time_t` (as a `u64`),
+    /// and is the same time representation as used in many Internet protocols.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -617,6 +633,9 @@ impl fmt::Debug for SystemTime {
 
 /// An anchor in time which can be used to create new `SystemTime` instances or
 /// learn about where in time a `SystemTime` lies.
+//
+// NOTE! this documentation is duplicated, here and in SystemTime::UNIX_EPOCH.
+// The two copies are not quite identical, because of the difference in naming.
 ///
 /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with
 /// respect to the system clock. Using `duration_since` on an existing
@@ -624,6 +643,11 @@ impl fmt::Debug for SystemTime {
 /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a
 /// [`SystemTime`] instance to represent another fixed point in time.
 ///
+/// `duration_since(UNIX_EPOCH).unwrap().as_secs()` returns
+/// the number of non-leap seconds since the start of 1970 UTC.
+/// This is a POSIX `time_t` (as a `u64`),
+/// and is the same time representation as used in many Internet protocols.
+///
 /// # Examples
 ///
 /// ```no_run