From 349ae4118b5efb0bad1231784afb9d03d4d5eb7c Mon Sep 17 00:00:00 2001 From: Warren Block Date: Sat, 27 Jun 2015 00:25:33 +0000 Subject: [PATCH] Add a short article on how FreeBSD handles leap seconds. Thanks for contributions from Peter Jeremy, Poul-Henning Kamp, Ian Lepore, Xin LI, and Warner Losh. Requested by Bartek Rutkowski. --- en_US.ISO8859-1/articles/Makefile | 1 + .../articles/leap-seconds/Makefile | 19 +++ .../articles/leap-seconds/article.xml | 118 ++++++++++++++++++ en_US.ISO8859-1/htdocs/docs/books.xml | 4 + share/xml/urls.ent | 2 + 5 files changed, 144 insertions(+) create mode 100644 en_US.ISO8859-1/articles/leap-seconds/Makefile create mode 100644 en_US.ISO8859-1/articles/leap-seconds/article.xml diff --git a/en_US.ISO8859-1/articles/Makefile b/en_US.ISO8859-1/articles/Makefile index 5cf056d36d..8c4987c6ff 100644 --- a/en_US.ISO8859-1/articles/Makefile +++ b/en_US.ISO8859-1/articles/Makefile @@ -17,6 +17,7 @@ SUBDIR+= gjournal-desktop SUBDIR+= hubs SUBDIR+= ipsec-must SUBDIR+= ldap-auth +SUBDIR+= leap-seconds SUBDIR+= linux-emulation SUBDIR+= linux-users SUBDIR+= mailing-list-faq diff --git a/en_US.ISO8859-1/articles/leap-seconds/Makefile b/en_US.ISO8859-1/articles/leap-seconds/Makefile new file mode 100644 index 0000000000..890b94f26e --- /dev/null +++ b/en_US.ISO8859-1/articles/leap-seconds/Makefile @@ -0,0 +1,19 @@ +# +# $FreeBSD$ +# +# Article: Leap Seconds + +DOC?= article + +FORMATS?= html +WITH_ARTICLE_TOC?= YES + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +SRCS= article.xml + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/leap-seconds/article.xml b/en_US.ISO8859-1/articles/leap-seconds/article.xml new file mode 100644 index 0000000000..93d076549d --- /dev/null +++ b/en_US.ISO8859-1/articles/leap-seconds/article.xml @@ -0,0 +1,118 @@ + + + +
+ + + &os; Support for Leap Seconds + + $FreeBSD$ + + + + Introduction + + A leap second is an ad-hoc one-second + correction to synchronize atomic timescales with Earth rotation. + This article describes how &os; interacts with leap + seconds. + + As of this writing, the next leap second will occur at + 2015-Jun-30 23:59:60. This particular leap second is unusual, + being in the middle of a business day for North and South + America and the Asia/Pacific region. + + Leap seconds are announced by IERS + on Bulletin + C. + + Standard leap second behavior is described in RFC + 7164. Also see &man.time2posix.3;. + + + + Default Leap Second Handling on &os; + + The easiest way to handle leap seconds is with the + POSIX time rules &os; uses by default, + combined with NTP. + When &man.ntpd.8; is running and the time is synchronized with + upstream NTP servers that handle leap seconds + correctly, the leap second will cause the system time to + automatically repeat the last second of the day. No other + adjustments are necessary. + + If the upstream NTP servers do not handle + leap seconds correctly, &man.ntpd.8; will step the time by one + second after the errant upstream server has noticed and stepped + itself. + + If NTP is not being used, manual + adjustment of the system clock will be required after the leap + second has passed. + + + + Cautions + + Leap seconds are inserted at the same instant all over the + world: UTC midnight. In Japan that is + mid-morning, in the Pacific mid-day, in the Americas late + afternoon, and in Europe at night. + + We believe and expect that &os;, if provided correct and + stable NTP service, will work as designed + during this leap second, as it did during the previous + ones. + + However, we caution that practically no applications have + ever asked the kernel about leap seconds. Our experience is + that, as designed, leap seconds are essentially a replay of the + second before the leap second, and this is a surprise to most + application programmers. + + Other operating systems and other computers may or may not + handle the leap-second the same way as &os;, and systems without + correct and stable NTP service will not know + anything about leap seconds at all. + + It is not unheard of for computers to crash because of + leap seconds, and experience has shown that a large fraction + of all public NTP servers might handle and + announce the leap second incorrectly. + + Please try to make sure nothing horrible happens because of + the leap second. + + + + Testing + + It is possible to test whether a leap second will be used. + Due to the nature of NTP, the test might work + up to 24 hours before the leap second. Some major reference + clock sources only announce leap seconds one hour ahead of the + event. Query the NTP daemon: + + &prompt.user; ntpq -c 'rv 0 leap' + + Output that includes leap_add_sec + indicates proper support of the leap second. Before the 24 hour + period before the leap second, or after the leap second has + passed, leap_none will be reported. + + + + Conclusion + + We hope this discussion of leap seconds on &os; has been of + use. Now let us never speak of it again. + +
diff --git a/en_US.ISO8859-1/htdocs/docs/books.xml b/en_US.ISO8859-1/htdocs/docs/books.xml index 20292dd546..92ce4450f2 100644 --- a/en_US.ISO8859-1/htdocs/docs/books.xml +++ b/en_US.ISO8859-1/htdocs/docs/books.xml @@ -170,6 +170,10 @@ A practical guide about setting up an LDAP server on &os; and how to use it for authenticating users.

+

&os; Support + for Leap Seconds (leap-seconds)
+ A short description of how leap seconds are handled on &os;.

+

Linux emulation in &os; (linux-emulation)
A technical description about the internals of the Linux diff --git a/share/xml/urls.ent b/share/xml/urls.ent index e6f6239864..3e170f3fc6 100644 --- a/share/xml/urls.ent +++ b/share/xml/urls.ent @@ -75,6 +75,8 @@ + +