svn commit: r46873 - in head: en_US.ISO8859-1/articles en_US.ISO8859-1/articles/leap-seconds en_US.ISO8859-1/htdocs/docs share/xml
Warren Block
wblock at FreeBSD.org
Sat Jun 27 00:25:35 UTC 2015
Author: wblock
Date: Sat Jun 27 00:25:33 2015
New Revision: 46873
URL: https://svnweb.freebsd.org/changeset/doc/46873
Log:
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.
Added:
head/en_US.ISO8859-1/articles/leap-seconds/
head/en_US.ISO8859-1/articles/leap-seconds/Makefile (contents, props changed)
head/en_US.ISO8859-1/articles/leap-seconds/article.xml (contents, props changed)
Modified:
head/en_US.ISO8859-1/articles/Makefile
head/en_US.ISO8859-1/htdocs/docs/books.xml
head/share/xml/urls.ent
Modified: head/en_US.ISO8859-1/articles/Makefile
==============================================================================
--- head/en_US.ISO8859-1/articles/Makefile Fri Jun 26 23:03:20 2015 (r46872)
+++ head/en_US.ISO8859-1/articles/Makefile Sat Jun 27 00:25:33 2015 (r46873)
@@ -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
Added: head/en_US.ISO8859-1/articles/leap-seconds/Makefile
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/en_US.ISO8859-1/articles/leap-seconds/Makefile Sat Jun 27 00:25:33 2015 (r46873)
@@ -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"
Added: head/en_US.ISO8859-1/articles/leap-seconds/article.xml
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/en_US.ISO8859-1/articles/leap-seconds/article.xml Sat Jun 27 00:25:33 2015 (r46873)
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
+ "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
+
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="leapseconds">
+
+ <info>
+ <title>&os; Support for Leap Seconds</title>
+
+ <pubdate>$FreeBSD$</pubdate>
+ </info>
+
+ <sect1 xml:id="leapseconds-definition">
+ <title>Introduction</title>
+
+ <para>A <emphasis>leap second</emphasis> is an ad-hoc one-second
+ correction to synchronize atomic timescales with Earth rotation.
+ This article describes how &os; interacts with leap
+ seconds.</para>
+
+ <para>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.</para>
+
+ <para>Leap seconds are announced by <link
+ xlink:href="http://datacenter.iers.org/"><acronym>IERS</acronym></link>
+ on <link
+ xlink:href="http://datacenter.iers.org/web/guest/bulletins/-/somos/5Rgv/product/16">Bulletin
+ C</link>.</para>
+
+ <para>Standard leap second behavior is described in <link
+ xlink:href="https://tools.ietf.org/html/rfc7164#section-3">RFC
+ 7164</link>. Also see &man.time2posix.3;.</para>
+ </sect1>
+
+ <sect1 xml:id="leapseconds-posix">
+ <title>Default Leap Second Handling on &os;</title>
+
+ <para>The easiest way to handle leap seconds is with the
+ <acronym>POSIX</acronym> time rules &os; uses by default,
+ combined with <link
+ xlink:href="&url.books.handbook;/network-ntp.html"><acronym>NTP</acronym></link>.
+ When &man.ntpd.8; is running and the time is synchronized with
+ upstream <acronym>NTP</acronym> 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.</para>
+
+ <para>If the upstream <acronym>NTP</acronym> 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.</para>
+
+ <para>If <acronym>NTP</acronym> is not being used, manual
+ adjustment of the system clock will be required after the leap
+ second has passed.</para>
+ </sect1>
+
+ <sect1 xml:id="leapseconds-cautions">
+ <title>Cautions</title>
+
+ <para>Leap seconds are inserted at the same instant all over the
+ world: <acronym>UTC</acronym> midnight. In Japan that is
+ mid-morning, in the Pacific mid-day, in the Americas late
+ afternoon, and in Europe at night.</para>
+
+ <para>We believe and expect that &os;, if provided correct and
+ stable <acronym>NTP</acronym> service, will work as designed
+ during this leap second, as it did during the previous
+ ones.</para>
+
+ <para>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.</para>
+
+ <para>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 <acronym>NTP</acronym> service will not know
+ anything about leap seconds at all.</para>
+
+ <para>It is not unheard of for computers to crash because of
+ leap seconds, and experience has shown that a large fraction
+ of all public <acronym>NTP</acronym> servers might handle and
+ announce the leap second incorrectly.</para>
+
+ <para>Please try to make sure nothing horrible happens because of
+ the leap second.</para>
+ </sect1>
+
+ <sect1 xml:id="leapseconds-testing">
+ <title>Testing</title>
+
+ <para>It is possible to test whether a leap second will be used.
+ Due to the nature of <acronym>NTP</acronym>, 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 <acronym>NTP</acronym> daemon:</para>
+
+ <screen>&prompt.user; <userinput>ntpq -c 'rv 0 leap'</userinput></screen>
+
+ <para>Output that includes <literal>leap_add_sec</literal>
+ indicates proper support of the leap second. Before the 24 hour
+ period before the leap second, or after the leap second has
+ passed, <literal>leap_none</literal> will be reported.</para>
+ </sect1>
+
+ <sect1 xml:id="leapseconds-conclusion">
+ <title>Conclusion</title>
+
+ <para>We hope this discussion of leap seconds on &os; has been of
+ use. Now let us never speak of it again.</para>
+ </sect1>
+</article>
Modified: head/en_US.ISO8859-1/htdocs/docs/books.xml
==============================================================================
--- head/en_US.ISO8859-1/htdocs/docs/books.xml Fri Jun 26 23:03:20 2015 (r46872)
+++ head/en_US.ISO8859-1/htdocs/docs/books.xml Sat Jun 27 00:25:33 2015 (r46873)
@@ -170,6 +170,10 @@
A practical guide about setting up an LDAP server on &os; and
how to use it for authenticating users.</p>
+ <p><a href="&url.articles;/leap-seconds/index.html">&os; Support
+ for Leap Seconds</a> (leap-seconds)<br/>
+ A short description of how leap seconds are handled on &os;.</p>
+
<p><a href="&url.articles;/linux-emulation/index.html">Linux
emulation in &os;</a> (linux-emulation)<br/>
A technical description about the internals of the Linux
Modified: head/share/xml/urls.ent
==============================================================================
--- head/share/xml/urls.ent Fri Jun 26 23:03:20 2015 (r46872)
+++ head/share/xml/urls.ent Sat Jun 27 00:25:33 2015 (r46873)
@@ -75,6 +75,8 @@
<!ENTITY url.articles.ipsec-must.en "&url.doc.langbase.en;/articles/ipsec-must">
<!ENTITY url.articles.ldap-auth "&url.doc.langbase;/articles/ldap-auth">
<!ENTITY url.articles.ldap-auth.en "&url.doc.langbase.en;/articles/ldap-auth">
+<!ENTITY url.articles.leap-seconds "&url.doc.langbase;/articles/leap-seconds">
+<!ENTITY url.articles.leap-seconds.en "&url.doc.langbase.en;/articles/leap-seconds">
<!ENTITY url.articles.linux-emulation "&url.doc.langbase;/articles/linux-emulation">
<!ENTITY url.articles.linux-emulation.en "&url.doc.langbase.en;/articles/linux-emulation">
<!ENTITY url.articles.linux-users "&url.doc.langbase;/articles/linux-users">
More information about the svn-doc-all
mailing list