Date: Sat, 27 Jun 2015 00:25:34 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: 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 Message-ID: <201506270025.t5R0PY7s073007@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201506270025.t5R0PY7s073007>